[LON-CAPA-cvs] cvs: doc /help render.texxml.pl texxml2latex.pl
bowersj2
lon-capa-cvs@mail.lon-capa.org
Tue, 02 Sep 2003 18:29:58 -0000
bowersj2 Tue Sep 2 14:29:58 2003 EDT
Modified files:
/doc/help texxml2latex.pl render.texxml.pl
Log:
Terminate renders on failure. (And some other crap, notably a hack for
pod2latex to work on files like "lonsql" that don't have .pm.)
Index: doc/help/texxml2latex.pl
diff -u doc/help/texxml2latex.pl:1.8 doc/help/texxml2latex.pl:1.9
--- doc/help/texxml2latex.pl:1.8 Mon Jul 21 16:32:08 2003
+++ doc/help/texxml2latex.pl Tue Sep 2 14:29:58 2003
@@ -66,7 +66,8 @@
if ($tag eq 'file') {
my $file = $attr->{'name'};
- open (LATEX_FILE, $dirprefix . $file);
+ open (LATEX_FILE, $dirprefix . $file) or
+ ($! = 1, die "Can't find LaTeX file $dirprefix/$file; terminating build.");
print <LATEX_FILE>;
print "\n\n";
}
@@ -89,9 +90,20 @@
$file = '../../loncom/' . $file;
my $filename = substr($file, rindex($file, '/') + 1);
system ("cp $file $tmpdir\n");
+ my $latexFile;
+ if (index($filename, '.') == -1) {
+ # pod2latex *insists* that either the extension of the
+ # file be .pl|.pm|.pod or that it be executable. Some
+ # extension-less files like "lonsql' are none-of-the-above.
+ system ("cd $tmpdir; mv $filename $filename.pm");
+ $filename .= ".pm";
+ print STDERR $filename . "\n";
+ }
system ("cd $tmpdir; pod2latex -h1level $h1level $section $filename\n");
- my $latexFile = substr($filename, 0, rindex($filename, '.')) . '.tex';
- open LATEX_FILE, $tmpdir . '/' . $latexFile;
+ $latexFile = substr($filename, 0, rindex($filename, '.')) . '.tex';
+ open LATEX_FILE, $tmpdir . '/' . $latexFile or
+ ($! = 1, die "Latex file $latexFile not found while trying to use pod2latex, ".
+ "terminating build");
# pod2latex inserts \labels and \indexs for every section,
# which is horrible because the section names tend to get
# reused a lot. This filters those out, so we need to do
@@ -231,22 +243,23 @@
beginning and C<Latex_Footer.tex> at the end, to make a complete
document LaTeX document.
-=head2 Rendering texxml X<texxml, rendering>
+=head2 Rendering texxml
-=head3 render.texxml.pl X<render.texxml.pl>
+=head3 render.texxml.pl
-The C<render.texxml.pl> script takes a .texxml file, and produces
-PostScript and PDF files. The LaTeX files will be given access to .eps
-files in the C</loncom/html/adm/help/eps/> directory while
-rendering. Call it as follows, from the C<doc/help> directory:
+X<texxml, rendering>X<render.texxml.pl>The C<render.texxml.pl> script
+takes a .texxml file, and produces PostScript and PDF files. The LaTeX
+files will be given access to .eps files in the
+C</loncom/html/adm/help/eps/> directory while rendering. Call it as
+follows, from the C<doc/help> directory:
perl render.texxml.pl -- author.manual.texxml
substituting the appropriate texxml file.
-=head3 texxml2latex.pl X<texxml2latex.pl>
+=head3 texxml2latex.pl
-texxml2latex.pl is a perl script that takes texxml in and assembles
+X<texxml2latex.pl>texxml2latex.pl is a perl script that takes texxml in and assembles
the final LaTeX file, outputting it on stout. Invoke it as follows:
perl texxml2latex.pl author.manual.texx
@@ -256,9 +269,9 @@
final render, it either could not be found, or you do not have
sufficient permissions with the current user to read it.
-=head3 texxml2index.pl X<texxml2index.pl>
+=head3 texxml2index.pl
-texxml2index.pl is a perl script that takes texxml in and assembles a
+X<texxml2index.pl>texxml2index.pl is a perl script that takes texxml in and assembles a
file that can be used online to access all the .tex files that are
specified in the .texxml file. For an example of how this looks
online, see
@@ -269,9 +282,9 @@
There are a couple of scripts that you may find useful for creating
texxml-based help:
-=head3 latexSplitter.py X<latexSplitter.py>
+=head3 latexSplitter.py
-latexSplitter.py is a Python script that helps you seperate a
+X<latexSplitter.py>latexSplitter.py is a Python script that helps you seperate a
monolithic .tex file into the small pieces LON-CAPA's help system
expects. Invoke it like this:
@@ -295,9 +308,9 @@
from scratch, you can use a "real" program like LyX to create the .tex
file, then easily split it with this program.
-=head3 simpleEdit.py X<simpleEdit.py>
+=head3 simpleEdit.py
-simpleEdit.py is a python script that takes a .texxml file and shows
+X<simpleEdit.py>simpleEdit.py is a python script that takes a .texxml file and shows
all the tex files that went into in sequence, allowing you to "edit"
the entire document as one entity. Note this is intended for simple
typo corrections and such in context, not major modification of the
@@ -331,8 +344,9 @@
LaTeX has a popular index making package called MakeIndex. LON-CAPA's
help system supports this, so you can create indices using the \index
LaTeX command. In perl POD files, use the X command. Note that in both
-cases the index text is not included in the render, so you need to
-specify the exact index.
+cases the index text is not included in the render, so the index must
+be included in addition to the indexed text, and need not match the
+indexed text precisely.
=head1 Writing POD: Style
@@ -370,15 +384,24 @@
The remainder should be formatted as appropriate for the file, such
that discarding the NAME, SYNOPSIS, and OVERVIEW sections provides a
-useful API overview of the module.
+useful API overview of the module. This may be anything from an
+elaborate discussion of the data structures, algorithms, and design
+principles that went into the module, or a simple listing of
+what functions exist, how to call them, and what they return, as
+appropriate.
Routines that are private to the module should B<not> be documented;
document them in perl comments, or, as is the style of the time, not
at all, as is appropriate.
Method and function names should be bolded when being
-documented. Indexing should be done as appropriate, using the X
-perldoc command. Literal string such as filename should be enclosed in
+documented.
+
+Literal string such as filename should be enclosed in
the C command, like this: C</home/httpd/lonTabs/>.
+
+Indexing can be done with the X command in perldoc, and should be used
+as appropriate. Do not include X commands in the headings, the output
+from pod2latex screws up some regexes in texxml2latex.pl.
=cut
Index: doc/help/render.texxml.pl
diff -u doc/help/render.texxml.pl:1.14 doc/help/render.texxml.pl:1.15
--- doc/help/render.texxml.pl:1.14 Thu Jul 24 10:47:58 2003
+++ doc/help/render.texxml.pl Tue Sep 2 14:29:58 2003
@@ -66,13 +66,16 @@
$epssource = $ARGV[2];
}
-my $redir = ">& /dev/null"; # empty this for easier debugging
-#my $redir = ">> error_log.txt";
+#my $redir = ">& /dev/null"; # empty this for easier debugging
+my $redir = ">> /home/jerf/error_log.txt";
mkdir $tmpdir, 0755;
print "Converting texxml to tex...\n";
-system ( "perl texxml2latex.pl $fileroot.texxml > $tmpdir/$fileroot.tex" );
+if (system ( "perl texxml2latex.pl $fileroot.texxml > $tmpdir/$fileroot.tex" )) {
+ $! = 1;
+ die "Terminated render because texxml2latex failed; see previous error message.";
+};
print "Copying .eps files...\n";
system ( "cp $epssource/* $tmpdir/" );