--- doc/help/texxml2latex.pl 2003/07/21 20:32:08 1.8 +++ doc/help/texxml2latex.pl 2003/09/02 18:29:58 1.9 @@ -66,7 +66,8 @@ while (my $token = $p->get_token()) 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 ; print "\n\n"; } @@ -89,9 +90,20 @@ while (my $token = $p->get_token()) $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 @@ texxml2latex.pl will automatically inclu beginning and C at the end, to make a complete document LaTeX document. -=head2 Rendering texxml X +=head2 Rendering texxml -=head3 render.texxml.pl X +=head3 render.texxml.pl -The C script takes a .texxml file, and produces -PostScript and PDF files. The LaTeX files will be given access to .eps -files in the C directory while -rendering. Call it as follows, from the C directory: +XXThe C script +takes a .texxml file, and produces PostScript and PDF files. The LaTeX +files will be given access to .eps files in the +C directory while rendering. Call it as +follows, from the C directory: perl render.texxml.pl -- author.manual.texxml substituting the appropriate texxml file. -=head3 texxml2latex.pl X +=head3 texxml2latex.pl -texxml2latex.pl is a perl script that takes texxml in and assembles +Xtexxml2latex.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 @@ Note that there is no error handling; if 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 +=head3 texxml2index.pl -texxml2index.pl is a perl script that takes texxml in and assembles a +Xtexxml2index.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 @@ C +=head3 latexSplitter.py -latexSplitter.py is a Python script that helps you seperate a +XlatexSplitter.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 @@ The idea behind this program is that if 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 +=head3 simpleEdit.py -simpleEdit.py is a python script that takes a .texxml file and shows +XsimpleEdit.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 @@ you can freely use references, even in o 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 @@ is read. 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 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. +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