Annotation of doc/help/texxml2latex.pl, revision 1.8

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>