Return to texxml2latex.pl CVS log

Up to [LON-CAPA] / doc / help

Terminate renders on failure. (And some other crap, notably a hack for
pod2latex to work on files like "lonsql" that don't have .pm.)

    1: #!/usr/bin/perl
    2: 
    3: # The LearningOnline Network with CAPA
    4: # Converts a texxml file into a single tex file
    5: #
    6: # Copyright Michigan State University Board of Trustees
    7: #
    8: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
    9: #
   10: # LON-CAPA is free software; you can redistribute it and/or modify
   11: # it under the terms of the GNU General Public License as published by
   12: # the Free Software Foundation; either version 2 of the License, or
   13: # (at your option) any later version.
   14: #
   15: # LON-CAPA is distributed in the hope that it will be useful,
   16: # but WITHOUT ANY WARRANTY; without even the implied warranty of
   17: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   18: # GNU General Public License for more details.
   19: #
   20: # You should have received a copy of the GNU General Public License
   21: # along with LON-CAPA; if not, write to the Free Software
   22: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   23: #
   24: # /home/httpd/html/adm/gpl.txt
   25: #
   26: # http://www.lon-capa.org/
   27: #
   28: # 7-16-2002 Jeremy Bowers
   29: 
   30: use strict;
   31: use HTML::TokeParser;
   32: use GDBM_File;
   33: use File::Temp;
   34: 
   35: # accept texxml document on standard in
   36: my $p = HTML::TokeParser->new( $ARGV[0] );
   37: my $dirprefix = "../../loncom/html/adm/help/tex/";
   38: 
   39: # Make myself a temp dir for processing POD
   40: my $tmpdir = File::Temp::tempdir('loncapahelpgenXXXXXXX', TMPDIR => 1);
   41: 
   42: # Print the header
   43: open (LATEX_FILE, $dirprefix . "Latex_Header.tex");
   44: print <LATEX_FILE>;
   45: 
   46: while (my $token = $p->get_token())
   47: {
   48:     my $type = $token->[0];
   49:     if ($type eq 'S') {
   50: 	my $tag = $token->[1];
   51: 	my $attr = $token->[2];
   52: 	if ($tag eq 'section') {
   53: 	    my $title = $attr->{'name'};
   54: 	    print "\\section{$title}\n\n";
   55: 	}
   56: 
   57: 	if ($tag eq 'subsection') {
   58: 	    my $title = $attr->{'name'};
   59: 	    print "\\subsection{$title}\n\n";
   60: 	}
   61: 
   62: 	if ($tag eq 'subsubsection') {
   63: 	    my $title = $attr->{'name'};
   64: 	    print "\\subsubsection{$title}\n\n";
   65: 	}
   66: 
   67: 	if ($tag eq 'file') {
   68: 	    my $file = $attr->{'name'};
   69: 	    open (LATEX_FILE, $dirprefix . $file) or 
   70: 		($! = 1, die "Can't find LaTeX file $dirprefix/$file; terminating build.");
   71: 	    print <LATEX_FILE>;
   72: 	    print "\n\n";
   73: 	}
   74: 
   75: 	if ($tag eq 'tex') {
   76: 	    print "\n\n";
   77: 	    print $attr->{'content'};
   78: 	    print "\n\n";
   79: 	}
   80: 
   81: 	if ($tag eq 'pod') {
   82: 	    my $file = $attr->{'file'};
   83: 	    my $section = $attr->{'section'};	    
   84: 	    if (!defined($section)) { $section = ''; }
   85: 	    else { 
   86: 		$section = "-section '$section'";
   87: 	    }
   88: 	    my $h1level = $attr->{'h1level'};
   89: 	    if (!defined($h1level)) { $h1level = '2'; }
   90: 	    $file = '../../loncom/' . $file;
   91: 	    my $filename = substr($file, rindex($file, '/') + 1);
   92: 	    system ("cp $file $tmpdir\n");
   93: 	    my $latexFile;
   94: 	    if (index($filename, '.') == -1) {
   95: 		# pod2latex *insists* that either the extension of the
   96: 		# file be .pl|.pm|.pod or that it be executable. Some
   97: 		# extension-less files like "lonsql' are none-of-the-above.
   98: 		system ("cd $tmpdir; mv $filename $filename.pm");
   99: 		$filename .= ".pm";
  100: 		print STDERR $filename . "\n";
  101: 	    }
  102: 	    system ("cd $tmpdir; pod2latex -h1level $h1level $section $filename\n");
  103: 	    $latexFile = substr($filename, 0, rindex($filename, '.')) . '.tex';
  104: 	    open LATEX_FILE, $tmpdir . '/' . $latexFile or
  105: 		($! = 1, die "Latex file $latexFile not found while trying to use pod2latex, ".
  106: 		 "terminating build");
  107: 	    # pod2latex inserts \labels and \indexs for every section,
  108: 	    # which is horrible because the section names tend to get
  109: 	    # reused a lot. This filters those out, so we need to do
  110: 	    # create our own indexes.
  111: 	    for (<LATEX_FILE>) {
  112: 		$_ =~ s/\\([^{]*)(section|paragraph)(\*?)\{([^\\]+)\\label\{[^\\]+\}\\index\{([^\\]+)\}\}/\\\1\2\3\{\4\}/g;
  113: 		print $_;
  114: 	    }
  115: 	    print "\n\n";
  116: 	}
  117:     }
  118: }
  119: 
  120: # Print out the footer.
  121: open (LATEX_FILE, $dirprefix . "Latex_Footer.tex");
  122: print <LATEX_FILE>;
  123: 
  124: # Remove the temp directory
  125: system ("rm -rf $tmpdir");
  126: 
  127: __END__
  128: 
  129: =pod
  130: 
  131: =head1 NAME
  132: 
  133: texxml2latex.pl - core script that drives the help file assembly
  134:   applications
  135: 
  136: =head1 SYNOPSIS
  137: 
  138: LON-CAPA's help system is based on assembling various pieces into
  139: LaTeX files for conversion into printed documents. The various pieces
  140: can also be used as online help.
  141: 
  142: =head1 OVERVIEW
  143: 
  144: X<help system, overview>LON-CAPA's help system is based on the idea of
  145: assembling various pieces as needed to create documents for printing,
  146: and using these various pieces for online help. LaTeX is the primary
  147: language of the help system, because we can easily convert it to HTML,
  148: and it makes the nicest printed documents.
  149: 
  150: The scripts for the help system are stored in /docs/help in the CVS
  151: repository.
  152: 
  153: =head2 Data Sources
  154: 
  155: The help system can draw from the following sources to create help
  156: documents:
  157: 
  158: =over 4
  159: 
  160: =item * B<LaTeX fragments>: LaTeX fragments stored in
  161: C</loncom/html/adm/help/tex> in the CVS repository (which end up in
  162: C</home/httpd/html/adm/help/tex>). A "LaTeX fragment" is a file that
  163: contains LaTeX-style markup, but is not a complete LaTeX file with
  164: header and footer.
  165: 
  166: =item * B<perl POD documentation>: POD documentation may be extracted
  167: from perl modules used in LON-CAPA, using the syntax described in
  168: podselect's man page.
  169: 
  170: =back
  171: 
  172: =head2 Online Help
  173: 
  174: The online aspect of the help system is covered in the documentation
  175: for loncommon.pm; see L<Apache::loncommon>, look for
  176: C<help_open_topic>.
  177: 
  178: Online help can only come from LaTeX fragments.
  179: 
  180: Access to the printed documents is partially provided online by
  181: rendering the help files structure in a way that allows the user to
  182: click through to the underlying help files; see 
  183: L<http://msu.loncapa.org/adm/help/author.manual.access.hlp> for an
  184: example. It's not very good, but it's marginally better then nothing.
  185: 
  186: =head2 Offline Documents 
  187: 
  188: Offline documents are generated from XML documents which tell a
  189: rendering script how to assemble the various LaTeX fragments into a
  190: single LaTeX file, which is then rendered into PostScript and PDF
  191: files, suitable for download and printing. 
  192: 
  193: =head1 texxml And Rendering texxml
  194: 
  195: =head2 texxml 
  196: 
  197: X<texxml>
  198: texxml is a little XML file format used to specify to the texxml2*.pl
  199: scripts how to assemble the input sources into LaTeX documents. texxml
  200: files end in the .texxml extension, and there is one texxml file per
  201: final rendered document.
  202: 
  203: The texxml format is as follows: There is a root <texxml> element,
  204: with no attributes and the following children:
  205: 
  206: =over 4
  207: 
  208: =item * B<title>: The B<name> attribute of this tag is used as the
  209:    title of the document in texxml2index.pl; it is ignored in 
  210:    texxml2latex.pl. If you don't intend to offer online-access
  211:    to the rendered documents this may be skipped.
  212: 
  213: =item * B<section>, B<subsection>, and B<subsubsection>: These create
  214:    the corresponding environments in the output file. The B<name>
  215:    attribute is used to determine the name of the section.
  216: 
  217: =item * B<file>: The C<name> attribute specifies a LaTeX fragment by
  218:    filename. The file is assumed to be located in the
  219:    C<loncom/html/adm/help/tex/> directory in the CVS repository. The
  220:    C<.tex> is required.
  221: 
  222: =item * B<tex>: The contents of the B<content> attribute are directly
  223:    inserted into the rendered LaTeX file, followed by a paragraph
  224:    break. This is generally used for little connective paragraphs in
  225:    the documentation that don't make sense in the online help. See
  226:    C<author.manual.texxml> for several example usages.
  227: 
  228: =item * B<pod>: The B<file> attribute specified a file to draw the POD
  229:    documentation out of. The B<section> attribute is a section
  230:    specification matching the format specified in the man page of
  231:    podselect. By default, all POD will be included. The file is
  232:    assumed to be relative to the C<loncom> directory in the CVS
  233:    repository; you are allowed to escape from that with .. if
  234:    necessary. The B<h1level> attribute can be used to change 
  235:    the default depth of the headings; by default, this is set to 2,
  236:    which makes =head1 a "subsection". Setting this higher can allow
  237:    you to bundle several related pod files together; see 
  238:    developer.manual.texxml for examples.
  239: 
  240: =back
  241: 
  242: texxml2latex.pl will automatically include C<Latex_Header.tex> at the
  243: beginning and C<Latex_Footer.tex> at the end, to make a complete
  244: document LaTeX document.
  245: 
  246: =head2 Rendering texxml 
  247: 
  248: =head3 render.texxml.pl 
  249: 
  250: X<texxml, rendering>X<render.texxml.pl>The C<render.texxml.pl> script
  251: takes a .texxml file, and produces PostScript and PDF files. The LaTeX
  252: files will be given access to .eps files in the
  253: C</loncom/html/adm/help/eps/> directory while rendering. Call it as
  254: follows, from the C<doc/help> directory:
  255: 
  256:  perl render.texxml.pl -- author.manual.texxml
  257: 
  258: substituting the appropriate texxml file.
  259: 
  260: =head3 texxml2latex.pl 
  261: 
  262: X<texxml2latex.pl>texxml2latex.pl is a perl script that takes texxml in and assembles
  263: the final LaTeX file, outputting it on stout. Invoke it as follows:
  264: 
  265:  perl texxml2latex.pl author.manual.texx
  266: 
  267: Note that there is no error handling; if the script can not find a
  268: .tex file, it is simply ignored. Generally, if a file is not in the
  269: final render, it either could not be found, or you do not have
  270: sufficient permissions with the current user to read it.
  271: 
  272: =head3 texxml2index.pl 
  273: 
  274: X<texxml2index.pl>texxml2index.pl is a perl script that takes texxml in and assembles a
  275: file that can be used online to access all the .tex files that are
  276: specified in the .texxml file. For an example of how this looks
  277: online, see
  278: C<http://msu.loncapa.org/adm/help/author.manual.access.hlp>.
  279: 
  280: =head2 texxml support
  281: 
  282: There are a couple of scripts that you may find useful for creating
  283: texxml-based help:
  284: 
  285: =head3 latexSplitter.py 
  286: 
  287: X<latexSplitter.py>latexSplitter.py is a Python script that helps you seperate a
  288: monolithic .tex file into the small pieces LON-CAPA's help system
  289: expects. Invoke it like this:
  290: 
  291:  python latexSplitter.py monolithic.tex
  292: 
  293: where C<monolithic.tex> is the .tex file you want to split into
  294: pieces. This requires Python 2.1 or greater (2.0 may work); on many
  295: modern RedHat installs this is installed by default under the
  296: executable name C<python2>.
  297: 
  298: Use the program by highlighting the desired section, give it a file
  299: name in the textbox near the bottom, and hit the bottom button. The
  300: program will remove that text from the textbox, and create a file in
  301: the C<loncom/html/adm/help/tex/> directory containing that LaTeX. For
  302: consistency, you should use underscores rather then spaces in the
  303: filename, and note there are a few naming conventions for the .tex
  304: files, which you can see just by listing the
  305: C<loncom/html/adm/help/tex/> directory.
  306: 
  307: The idea behind this program is that if you are writing a big document
  308: from scratch, you can use a "real" program like LyX to create the .tex
  309: file, then easily split it with this program.
  310: 
  311: =head3 simpleEdit.py 
  312: 
  313: X<simpleEdit.py>simpleEdit.py is a python script that takes a .texxml file and shows
  314: all the tex files that went into in sequence, allowing you to "edit"
  315: the entire document as one entity. Note this is intended for simple
  316: typo corrections and such in context, not major modification of the
  317: document. Invoke it with 
  318: 
  319:  python simpleEdit.py author.manual.texxml
  320: 
  321: Make your changes, and hit the "Save" button to save them.
  322: 
  323: =head2 texxml LaTeX Feature Support
  324: 
  325: =head3 Cross-referencing
  326: 
  327: LaTeX has a cross-referencing system build around labeling points in
  328: the document with \label, and referencing those labels with \ref. In a
  329: complete LaTeX document, there's no problem because all \refs and
  330: \labels are present. However, for the online help, \ref'ing something
  331: that is not in the current LaTeX fragment causes a TTH error when it
  332: can't find the crossreference.
  333: 
  334: The solution is to do the cross-references for TTH. When LON-CAPA is
  335: installed, the C<rebuildLabelHahs.pl>X<rebuildLabelHash.pl> script
  336: is executed, which extracts all the labels from the LaTeX fragments
  337: and stores them in the C<fragmentLabels.gdbm>X<fragmentLabels.gdbm> hash. 
  338: The C<lonhelp.pm> handler then replaces \refs with appropriate
  339: HTML to provide a link to the referenced help file while online. Thus,
  340: you can freely use references, even in online help.
  341: 
  342: =head3 Indexing
  343: 
  344: LaTeX has a popular index making package called MakeIndex. LON-CAPA's
  345: help system supports this, so you can create indices using the \index
  346: LaTeX command. In perl POD files, use the X command. Note that in both
  347: cases the index text is not included in the render, so the index must 
  348: be included in addition to the indexed text, and need not match the 
  349: indexed text precisely.
  350: 
  351: =head1 Writing POD: Style
  352: 
  353: Adopting a little bit from everybody who has included POD in their
  354: documents to date, the help system is going to expect the following
  355: format for POD documentation.
  356: 
  357: The POD should start with a C<=head1> with the title C<NAME> (in caps
  358: as shown). The following paragraph should extremely briefly describe
  359: what the module does and contains. Example:
  360: 
  361:  =head1 NAME
  362: 
  363:  Apache::lonflunkstudent - provides interface to set all
  364:    student assessments point score to 0
  365: 
  366: Next should be a C<head1> titled C<SYNOPSIS> which contains a
  367: paragraph or two description of the module.
  368: 
  369:  =head1 SYNOPSIS
  370: 
  371:  lonflunkstudent provides a handler to select a student and set all
  372:  assignment values to zero, thereby flunking the student.
  373: 
  374:  Routines for setting all assessments to some value are provided by
  375:  this module, as well as some useful student taunting routines.
  376: 
  377: Optionally, an C<OVERVIEW> section can be included. This can then be
  378: extracted by the help system for the LON-CAPA subsystems overview
  379: chapter. The overview should be a relatively high-level, but still
  380: technical, overview of the module, sufficient to give the reader
  381: enough context to understand what the module does, what it might be
  382: useful for in other contexts, and what is going on in the code when it
  383: is read.
  384: 
  385: The remainder should be formatted as appropriate for the file, such
  386: that discarding the NAME, SYNOPSIS, and OVERVIEW sections provides a
  387: useful API overview of the module. This may be anything from an 
  388: elaborate discussion of the data structures, algorithms, and design 
  389: principles that went into the module, or a simple listing of 
  390: what functions exist, how to call them, and what they return, as
  391: appropriate.
  392: 
  393: Routines that are private to the module should B<not> be documented;
  394: document them in perl comments, or, as is the style of the time, not
  395: at all, as is appropriate.
  396: 
  397: Method and function names should be bolded when being
  398: documented. 
  399: 
  400: Literal string such as filename should be enclosed in
  401: the C command, like this: C</home/httpd/lonTabs/>. 
  402: 
  403: Indexing can be done with the X command in perldoc, and should be used 
  404: as appropriate. Do not include X commands in the headings, the output 
  405: from pod2latex screws up some regexes in texxml2latex.pl.
  406: 
  407: =cut