Tools/texdoclet
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #4 from cepr/master

Browse Source 
Misc improvements
This commit is contained in:
doclet
2015-03-21 21:19:56 +01:00
parent d1ac0bcc2f 7f55061a59
commit 1c653c9b0d
2 changed files with 139 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
src/main/java/org/stfm/texdoclet/HelpOutput.java
View File

@@ -61,6 +61,8 @@ public class HelpOutput {
System.err.println("-version Includes version-tags."); System.err.println("-version Includes version-tags.");
System.err System.err
.println("-hr Prints horizontal rows in the output (to get a better? view)."); .println("-hr Prints horizontal rows in the output (to get a better? view).");
System.err
.println("-nopackagetoc Do not include a table of content for each package");
System.err System.err
.println("-include Creates output in two separated latex documents: one for the preamble part and another for the actual java documentation content."); .println("-include Creates output in two separated latex documents: one for the preamble part and another for the actual java documentation content.");
System.err System.err
@@ -71,6 +73,10 @@ public class HelpOutput {
.println("-tablescale <factor> Scale factor to specify width of tables. Default value is 0.9."); .println("-tablescale <factor> Scale factor to specify width of tables. Default value is 0.9.");
System.err System.err
.println("-createpdf Creates .pdf file from the .tex output file by using pdflatex tool."); .println("-createpdf Creates .pdf file from the .tex output file by using pdflatex tool.");
System.err
.println("-packageorder <pkg1>,<pkg2>,...");
System.err
.println(" Use a specific package order.");
} }
} }

178
src/main/java/org/stfm/texdoclet/TeXDoclet.java
View File

@@ -239,6 +239,7 @@ public class TeXDoclet extends Doclet {
static boolean useFieldSummary = true; static boolean useFieldSummary = true;
static boolean useConstructorSummary = true; static boolean useConstructorSummary = true;
static boolean useHr = false; static boolean useHr = false;
static boolean usePackageToc = true;
static boolean shortInheritance = false; static boolean shortInheritance = false;
/** /**
* print writer for extra LaTeX preamble file * print writer for extra LaTeX preamble file
@@ -250,6 +251,7 @@ public class TeXDoclet extends Doclet {
static String introFile = null; static String introFile = null;
static double tableWidthScale = 0.9; static double tableWidthScale = 0.9;
static boolean createPdf = false; static boolean createPdf = false;
static String package_order = null;
static final String REPLACE_OUT = "_replace_data_"; static final String REPLACE_OUT = "_replace_data_";
static final String REPLACE_TITLE = "_replace_title_"; static final String REPLACE_TITLE = "_replace_title_";
static final String HTML_PDF_WRAPPER = "<!DOCTYPE html><html lang=\"en\" xml:lang=\"en\" xmlns=\"http://www.w3.org/1999/xhtml\"><head>" static final String HTML_PDF_WRAPPER = "<!DOCTYPE html><html lang=\"en\" xml:lang=\"en\" xmlns=\"http://www.w3.org/1999/xhtml\"><head>"
@@ -366,6 +368,8 @@ public class TeXDoclet extends Doclet {
return 2; return 2;
} else if (option.equals("-hr")) { } else if (option.equals("-hr")) {
return 1; return 1;
} else if (option.equals("-nopackagetoc")) {
return 1;
} else if (option.equals("-shortinherited")) { } else if (option.equals("-shortinherited")) {
return 1; return 1;
} else if (option.equals("-help")) { } else if (option.equals("-help")) {
@@ -383,6 +387,8 @@ public class TeXDoclet extends Doclet {
return 2; return 2;
} else if (option.equals("-createpdf")) { } else if (option.equals("-createpdf")) {
return 1; return 1;
} else if (option.equals("-packageorder")) {
return 2;
} }
System.out.println("unknown TeXDoclet option " + option); System.out.println("unknown TeXDoclet option " + option);
@@ -472,6 +478,8 @@ public class TeXDoclet extends Doclet {
sectionLevelMax = args[i][1]; sectionLevelMax = args[i][1];
} else if (args[i][0].equals("-hr")) { } else if (args[i][0].equals("-hr")) {
useHr = true; useHr = true;
} else if (args[i][0].equals("-nopackagetoc")) {
usePackageToc = false;
} else if (args[i][0].equals("-shortinherited")) { } else if (args[i][0].equals("-shortinherited")) {
shortInheritance = true; shortInheritance = true;
} else if (args[i][0].equals("-help")) { } else if (args[i][0].equals("-help")) {
@@ -487,6 +495,8 @@ public class TeXDoclet extends Doclet {
tableWidthScale = Double.parseDouble(args[i][1]); tableWidthScale = Double.parseDouble(args[i][1]);
} else if (args[i][0].equals("-createpdf")) { } else if (args[i][0].equals("-createpdf")) {
createPdf = true; createPdf = true;
} else if (args[i][0].equals("-packageorder")) {
package_order = args[i][1];
} }
if (sectionLevelMax != null if (sectionLevelMax != null
@@ -555,7 +565,7 @@ public class TeXDoclet extends Doclet {
os.println("\\thispagestyle{empty}"); os.println("\\thispagestyle{empty}");
os.println("\\markboth{Introduction}{Introduction}"); os.println("\\markboth{Introduction}{Introduction}");
printTags(root.inlineTags()); printTags(null, root.inlineTags());
os.println("}"); os.println("}");
} }
@@ -563,6 +573,32 @@ public class TeXDoclet extends Doclet {
ClassDoc[] cls = root.classes(); ClassDoc[] cls = root.classes();
PackageDoc[] specifiedPackages = root.specifiedPackages(); PackageDoc[] specifiedPackages = root.specifiedPackages();
// Sort the packages
if (package_order != null) {
String[] pkg = package_order.split(",");
for (int i = 0; i < pkg.length; i++) {
// Search for pkg[i] in the specifiedPackages
int j; boolean found = false;
for (j = i; j < specifiedPackages.length; j++) {
if (specifiedPackages[j].name().equals(pkg[i])) {
found = true;
break;
}
}
if (!found) {
System.err.println("Package " + pkg + " not found, aborting.");
return false;
}
if (i != j) {
// specifiedPackages has to be reordered
PackageDoc swap = specifiedPackages[i];
specifiedPackages[i] = specifiedPackages[j];
specifiedPackages[j] = swap;
}
}
}
System.out.println("specifiedPackages : " + specifiedPackages.length); System.out.println("specifiedPackages : " + specifiedPackages.length);
for (int i = 0; i < specifiedPackages.length; i++) { for (int i = 0; i < specifiedPackages.length; i++) {
Package P = new Package(specifiedPackages[i].name(), Package P = new Package(specifiedPackages[i].name(),
@@ -645,6 +681,7 @@ public class TeXDoclet extends Doclet {
// "\\markboth{\\protect\\packagename \\hspace{.02in} -- \\protect\\classname}{\\protect\\packagename \\hspace{.02in} -- \\protect\\classname}" // "\\markboth{\\protect\\packagename \\hspace{.02in} -- \\protect\\classname}{\\protect\\packagename \\hspace{.02in} -- \\protect\\classname}"
// ); // );
if (usePackageToc) {
if (ITALIC.indexOf("textit") != -1) { if (ITALIC.indexOf("textit") != -1) {
os.println("\\hskip -.05in"); os.println("\\hskip -.05in");
} }
@@ -660,13 +697,14 @@ public class TeXDoclet extends Doclet {
os.println("\\rule{\\hsize}{.7mm}"); os.println("\\rule{\\hsize}{.7mm}");
} }
os.println("\\vskip .1in"); os.println("\\vskip .1in");
}
// The path relative to which <IMG> will be resolved. // The path relative to which <IMG> will be resolved.
packageDir = findPackageDir(pkg.pkg, root); packageDir = findPackageDir(pkg.pkg, root);
// Package comments // Package comments
if (pkg.pkgDoc.inlineTags().length > 0) { if (pkg.pkgDoc.inlineTags().length > 0) {
printTags(pkg.pkgDoc.inlineTags()); printTags(pkg.pkgDoc, pkg.pkgDoc.inlineTags());
if (useHr) { if (useHr) {
os.println("\\mbox{}\\\\ \\rule{\\hsize}{.7mm}"); os.println("\\mbox{}\\\\ \\rule{\\hsize}{.7mm}");
@@ -813,6 +851,8 @@ public class TeXDoclet extends Doclet {
printPreambleUsePackages(os); printPreambleUsePackages(os);
printPreambleListingsOptions(os);
printPreambleIfPfd(os); printPreambleIfPfd(os);
printPreambleNewCommands(os); printPreambleNewCommands(os);
@@ -841,6 +881,11 @@ public class TeXDoclet extends Doclet {
} }
os.println("\\usepackage{ifpdf}"); os.println("\\usepackage{ifpdf}");
os.println("\\usepackage[" + style + "]{fullpage}"); os.println("\\usepackage[" + style + "]{fullpage}");
os.println("\\usepackage{listings}");
}
static void printPreambleListingsOptions(PrintWriter os) {
os.println("\\lstset{language=Java,breaklines=true}");
} }
static void printPreambleTitle(PrintWriter os) { static void printPreambleTitle(PrintWriter os) {
@@ -962,7 +1007,7 @@ public class TeXDoclet extends Doclet {
os.print("\\entityintro{" os.print("\\entityintro{"
+ HTMLtoLaTeXBackEnd.fixText(cd.name()) + "}" + "{" + HTMLtoLaTeXBackEnd.fixText(cd.name()) + "}" + "{"
+ refName(makeRefKey(cd.qualifiedName())) + "}" + "{"); + refName(makeRefKey(cd.qualifiedName())) + "}" + "{");
printTags(cd.firstSentenceTags()); printTags(cd.containingPackage(), cd.firstSentenceTags());
os.println("}"); os.println("}");
} }
} }
@@ -1097,7 +1142,7 @@ public class TeXDoclet extends Doclet {
os.println("\\vskip .1in "); os.println("\\vskip .1in ");
if (cd.inlineTags().length > 0) { if (cd.inlineTags().length > 0) {
printTags(cd.inlineTags()); printTags(cd.containingPackage(), cd.inlineTags());
os.println("\\vskip .1in "); os.println("\\vskip .1in ");
} }
@@ -1115,25 +1160,24 @@ public class TeXDoclet extends Doclet {
os.println("\\" + sectionLevels[2] + "{Declaration}{"); os.println("\\" + sectionLevels[2] + "{Declaration}{");
os.print("\\small " + HTMLtoLaTeXBackEnd.fixText(cd.modifiers()) os.println("\\begin{lstlisting}[frame=trBL]");
+ " "); os.print(cd.modifiers() + " ");
if (cd.isInterface() == false) { if (cd.isInterface() == false) {
os.print("class "); os.print("class ");
} }
os.println(HTMLtoLaTeXBackEnd.fixText(cd.name())); os.println(cd.name());
ClassDoc sc = cd.superclass(); ClassDoc sc = cd.superclass();
if (sc != null) { if (sc != null) {
os.println("\\\\ " + BOLD + " extends} " os.print(" extends "
+ HTMLtoLaTeXBackEnd.fixText(sc.qualifiedName())); + sc.qualifiedName());
printRef(sc.containingPackage(), sc.name(), null);
} }
ClassDoc intf[] = cd.interfaces(); ClassDoc intf[] = cd.interfaces();
if (intf.length > 0) { if (intf.length > 0) {
if (cd.isInterface() == false) { if (cd.isInterface() == false) {
os.println("\\\\ " + BOLD + " implements} "); os.print(" implements ");
} else { } else {
os.println("\\\\ " + BOLD + " extends} "); os.print(" extends ");
} }
for (int j = 0; j < intf.length; ++j) { for (int j = 0; j < intf.length; ++j) {
ClassDoc in = intf[j]; ClassDoc in = intf[j];
@@ -1147,10 +1191,10 @@ public class TeXDoclet extends Doclet {
if (j > 0) { if (j > 0) {
os.print(", "); os.print(", ");
} }
os.print(HTMLtoLaTeXBackEnd.fixText(nm)); os.print(nm);
} }
} }
os.println("}"); os.println("\\end{lstlisting}");
ExecutableMemberDoc[] mems; ExecutableMemberDoc[] mems;
FieldDoc[] flds; FieldDoc[] flds;
@@ -1400,7 +1444,7 @@ public class TeXDoclet extends Doclet {
os.println("\\begin{itemize}"); os.println("\\begin{itemize}");
if (f.inlineTags().length > 0) { if (f.inlineTags().length > 0) {
os.println("\\item{\\vskip -.9ex "); os.println("\\item{\\vskip -.9ex ");
printTags(f.inlineTags()); printTags(f.containingPackage(), f.inlineTags());
os.println("}"); os.println("}");
} }
@@ -1459,7 +1503,7 @@ public class TeXDoclet extends Doclet {
os.print("}"); os.print("}");
} }
os.print(" "); os.print(" ");
printTags(mem.firstSentenceTags()); printTags(mem.containingPackage(), mem.firstSentenceTags());
os.println("\\\\"); os.println("\\\\");
} }
os.println("\\end{verse}"); os.println("\\end{verse}");
@@ -1494,7 +1538,7 @@ public class TeXDoclet extends Doclet {
os.print("}"); os.print("}");
} }
os.print(" "); os.print(" ");
printTags(mem.firstSentenceTags()); printTags(mem.containingPackage(), mem.firstSentenceTags());
os.println("\\\\"); os.println("\\\\");
} }
os.println("\\end{verse}"); os.println("\\end{verse}");
@@ -1621,33 +1665,28 @@ public class TeXDoclet extends Doclet {
os.println(); os.println();
// Print signature // Print signature
os.print(TRUETYPE); os.println("\\begin{lstlisting}[frame=single]");
if (!mem.containingClass().isInterface()) { if (!mem.containingClass().isInterface()) {
os.print(HTMLtoLaTeXBackEnd.fixText(mem.modifiers())); os.print(mem.modifiers() + " ");
} }
if (mem instanceof MethodDoc) { if (mem instanceof MethodDoc) {
os.print(" " os.print(packageRelativIdentifier(pac, ((MethodDoc) mem)
+ HTMLtoLaTeXBackEnd.fixText(packageRelativIdentifier(pac, .returnType().toString()) + " ");
((MethodDoc) mem).returnType().toString())));
} }
os.print("\\ " + BOLD + " " + HTMLtoLaTeXBackEnd.fixText(mem.name()) os.print(mem.name() + "(");
+ "}(");
Parameter[] parms = mem.parameters(); Parameter[] parms = mem.parameters();
int p = 0; int p = 0;
String qparmstr = ""; String qparmstr = "";
String parmstr = ""; String parmstr = "";
for (; p < parms.length; ++p) { for (; p < parms.length; ++p) {
if (p > 0) { if (p > 0) {
os.println(","); os.print(",");
} }
Type t = parms[p].type(); Type t = parms[p].type();
os.print(TRUETYPE os.print(packageRelativIdentifier(pac, t.qualifiedTypeName()));
+ HTMLtoLaTeXBackEnd.fixText(packageRelativIdentifier(pac, os.print(t.dimension());
t.qualifiedTypeName())));
os.print(HTMLtoLaTeXBackEnd.fixText(t.dimension()) + "}");
if (parms[p].name().equals("") == false) { if (parms[p].name().equals("") == false) {
os.print(" " + BOLD + " " os.print(" " + parms[p].name());
+ HTMLtoLaTeXBackEnd.fixText(parms[p].name()) + "}");
} }
if (qparmstr.length() != 0) { if (qparmstr.length() != 0) {
qparmstr += ","; qparmstr += ",";
@@ -1668,19 +1707,7 @@ public class TeXDoclet extends Doclet {
os.print(", " + thrownExceptions[e].qualifiedName()); os.print(", " + thrownExceptions[e].qualifiedName());
} }
} }
os.println(); os.println("\\end{lstlisting} %end signature");
if (copiedTo == null) {
os.print("\\label{"
+ refName(makeRefKey(mem.qualifiedName() + mem.signature()))
+ "}");
} else {
os.print("\\label{"
+ refName(makeRefKey(copiedTo.qualifiedName()
+ copiedTo.signature())) + "}");
}
os.println("}%end signature");
boolean yet = false; boolean yet = false;
// Description // Description
@@ -1707,7 +1734,7 @@ public class TeXDoclet extends Doclet {
os.print("\\refdefined{" + refName(makeRefKey(classname)) + "}"); os.print("\\refdefined{" + refName(makeRefKey(classname)) + "}");
os.println("} }\n"); os.println("} }\n");
} }
printTags(mem.inlineTags()); printTags(mem.containingPackage(), mem.inlineTags());
os.println("\n}"); os.println("\n}");
} }
@@ -1725,7 +1752,7 @@ public class TeXDoclet extends Doclet {
os.print(TRUETYPE os.print(TRUETYPE
+ HTMLtoLaTeXBackEnd.fixText(params[j].parameterName()) + HTMLtoLaTeXBackEnd.fixText(params[j].parameterName())
+ "}" + " -- "); + "}" + " -- ");
printTags(params[j].inlineTags()); printTags(mem.containingPackage(), params[j].inlineTags());
os.println("}"); os.println("}");
} }
os.println(" \\end{itemize}"); os.println(" \\end{itemize}");
@@ -1742,7 +1769,7 @@ public class TeXDoclet extends Doclet {
} }
os.println("\\item{" + BOLD + " Returns} -- "); os.println("\\item{" + BOLD + " Returns} -- ");
for (int j = 0; j < ret.length; ++j) { for (int j = 0; j < ret.length; ++j) {
printTags(ret[j].inlineTags()); printTags(mem.containingPackage(), ret[j].inlineTags());
os.println(" "); os.println(" ");
} }
os.println("}%end item"); os.println("}%end item");
@@ -1767,7 +1794,7 @@ public class TeXDoclet extends Doclet {
} }
os.print(" \\item{\\vskip -.6ex " + TRUETYPE os.print(" \\item{\\vskip -.6ex " + TRUETYPE
+ HTMLtoLaTeXBackEnd.fixText(ename) + "} -- "); + HTMLtoLaTeXBackEnd.fixText(ename) + "} -- ");
printTags(excp[j].inlineTags()); printTags(mem.containingPackage(), excp[j].inlineTags());
os.println("}"); os.println("}");
} }
os.println(" \\end{itemize}"); os.println(" \\end{itemize}");
@@ -1979,7 +2006,7 @@ public class TeXDoclet extends Doclet {
/** /**
* Prints a sequence of tags obtained from e.g. com.sun.javadoc.Doc.tags(). * Prints a sequence of tags obtained from e.g. com.sun.javadoc.Doc.tags().
*/ */
static void printTags(Tag[] tags) { static void printTags(PackageDoc this_package, Tag[] tags) {
String htmlstr = new String(); String htmlstr = new String();
for (int i = 0; i < tags.length; i++) { for (int i = 0; i < tags.length; i++) {
@@ -1987,40 +2014,52 @@ public class TeXDoclet extends Doclet {
SeeTag link = (SeeTag) tags[i]; SeeTag link = (SeeTag) tags[i];
String linkstr = ""; String linkstr = "";
String label;
if (link.referencedMember() != null) { if (link.referencedMember() != null) {
MemberDoc member = link.referencedMember();
linkstr = member.qualifiedName();
label = classRelativeIdentifier(member.containingClass(), member.name());
if (link.referencedMember() instanceof ExecutableMemberDoc) { if (link.referencedMember() instanceof ExecutableMemberDoc) {
ExecutableMemberDoc m = (ExecutableMemberDoc) link // If the member is a method, append the method signature
.referencedMember(); ExecutableMemberDoc m = (ExecutableMemberDoc) member;
linkstr = m.qualifiedName() + m.signature(); linkstr += m.signature();
} else { label += m.flatSignature();
linkstr = link.referencedMember().qualifiedName();
} }
} else if (link.referencedClass() != null) { } else if (link.referencedClass() != null) {
linkstr = link.referencedClass().qualifiedName(); linkstr = link.referencedClass().qualifiedName();
label = packageRelativIdentifier(this_package, link.referencedClass().name());
} else if (link.referencedPackage() != null) { } else if (link.referencedPackage() != null) {
linkstr = link.referencedPackage().name(); linkstr = link.referencedPackage().name();
label = linkstr;
} else {
label = "";
} }
if (linkstr.equals("")) { if (linkstr.isEmpty()) {
htmlstr += link.text(); htmlstr += link.text();
} else { } else {
// Encapsulate the link in a "TEX" tag and let // Encapsulate the link in a "TEX" tag and let
// HTMLtoLaTeXBackEnd.fixText handle the rest. // HTMLtoLaTeXBackEnd.fixText handle the rest.
htmlstr += "<TEX txt=\""; htmlstr += "<TEX txt=\"\\texttt{\\small ";
if (hyperref) { if (hyperref) {
htmlstr += "\\hyperlink{" htmlstr += "\\hyperlink{"
+ refName(makeRefKey(linkstr)) + "}{"; + refName(makeRefKey(linkstr)) + "}{";
} }
htmlstr += HTMLtoLaTeXBackEnd.fixText(link.label()); if (!link.label().isEmpty()) {
label = link.label();
}
htmlstr += HTMLtoLaTeXBackEnd.fixText(label);
if (hyperref) { if (hyperref) {
htmlstr += "}"; htmlstr += "}";
} }
htmlstr += "{\\small \n"; htmlstr += "}{\\small \n";
htmlstr += "\\refdefined{" + refName(makeRefKey(linkstr)) htmlstr += "\\refdefined{" + refName(makeRefKey(linkstr))
+ "}"; + "}";
htmlstr += "}"; htmlstr += "}";
htmlstr += "\"></TEX>"; htmlstr += "\"></TEX>";
} }
} else if ("@code".equals(tags[i].name())) {
htmlstr += "<code>" + tags[i].text() + "</code>";
} else { } else {
htmlstr += tags[i].text(); htmlstr += tags[i].text();
} }
@@ -2061,13 +2100,34 @@ public class TeXDoclet extends Doclet {
* The identifier to be made relative. * The identifier to be made relative.
*/ */
static String packageRelativIdentifier(PackageDoc doc, String str) { static String packageRelativIdentifier(PackageDoc doc, String str) {
if (str.startsWith(doc.name() + ".")) { if (doc != null && str.startsWith(doc.name() + ".")) {
return str.substring(doc.name().length() + 1); return str.substring(doc.name().length() + 1);
} else { } else {
return str; return str;
} }
} }
/**
* Returns a class relative identifier.
*
* @param doc
* The class the identifier should be relative to.
* @param str
* The identifier to be made relative.
*/
static String classRelativeIdentifier(ClassDoc doc, String str) {
if (str.startsWith(doc.name())) {
// This is a member or a method of the same class
return str.substring(doc.name().length() + 1);
} else if (str.startsWith(doc.containingPackage().name())) {
// This is a member or a method of a different class but from the same package
return str.substring(doc.name().length() + 1);
} else {
// This is a member or a method from a different package, cannot be simplified
return str;
}
}
/** /**
* Prints a "see also" tag. * Prints a "see also" tag.
* *