diff --git a/Packages/Manual_tools/doc/latex_to_html.tex b/Packages/Manual_tools/doc/latex_to_html.tex new file mode 100644 index 00000000000..a4e16b91fde --- /dev/null +++ b/Packages/Manual_tools/doc/latex_to_html.tex @@ -0,0 +1,445 @@ +% ___________________________________________________________________________ +% |#########################################################################| +% | | +% | The Manual for the LaTeX converter lc_manual.tex | +% | ------------------------------------------------------------- | +% | | +% | 30.07.1998 Lutz Kettner kettner@acm.org | +% | Zurich, Switzerland | +% | $Revision$ | +% | $Date$ | +% |_________________________________________________________________________| +% |#########################################################################| + +\documentclass[12pt]{article} +\usepackage{latexsym} +\usepackage{amssymb} +\usepackage{path} +\usepackage{epsfig} +\usepackage{cc_manual} +\usepackage{latex_converter} +\usepackage{makeidx} +\makeindex + +%\pagestyle{empty} +\textwidth 15.4cm +\textheight 24 cm +\topmargin -14mm +\evensidemargin 3mm +\oddsidemargin 3mm + +\parindent0em +\setlength{\parskip}{1.4ex} + +\sloppy + +{ + \begingroup + \catcode`\|=0 + \catcode`\[=1 + \catcode`\]=2 + \catcode`\{=12 + \catcode`\}=12 + \catcode`\\=12 + |gdef|Open[[|tt {]] + |gdef|Close[[|tt }]] + |gdef|Backslash[[|tt \]] + |endgroup +} + +\newcommand{\Mindex}[1]{\index{#1@\protect\Backslash{\tt #1}}} +\newcommand{\ccIndex}[1]{\index{#1@\protect\Backslash{\tt cc#1}}} +\newcommand{\TTindex}[1]{\index{#1@{\tt #1}}} +\newcommand{\Dindex}[1]{#1\index{#1}} + +\def\ind{\hspace*{7mm}} + +% ---------------------------------------------------------------------- +\title{\LaTeX\ to HTML Converter\\ + {\tt latex\_converter} and {\tt latex\_to\_html}} +\author{Lutz Kettner} + +\date{\lcRevision. \lcDate} + +\begin{document} + +\maketitle + +\tableofcontents + +% ---------------------------------------------------------------------- +\section{Introduction} + + + +% ---------------------------------------------------------------------- +\section{Converting a Manual to {\tt HTML}} +\label{sectionHTML} +\index{tools}\index{converting to HTML@converting to {\tt HTML}} +\TTindex{HTML}\index{hyperlinks} + +The programs described in this section are not compatible with the +older versions of the {\tt cc\_manual.sty}, formerly {\tt + cgal\_manual.sty}. The old macro names are no longer recognized. Old +specifications has to be converted with the scripts provided. The +scripts are mentioned in Section~\ref{sectionChanges}. + +% ------------------------------------------------------- +\subsection{Manual Structure and Induced Output Files} + +\index{document structure}\index{structure of document}\index{online + manual} The tools for the conversion to an online {\tt HTML} manual +impose certain restrictions on the \LaTeX\ specification. Each chapter +and each class defining environment ({\tt ccClass}, {\tt + ccClassTemplate}, and {\tt ccHtmlClassFile}) opens a new file. For +chapters, the new files get the filename of the current \LaTeX\ file +with the prefix {\tt Chapter\_} and the new postfix {\tt .html}. For +class defining environments, the new files get the name of the class +as filename with the postfix {\tt .html} added. These conventions make +hyperlinking easier. A set of requirements and recommendations follow +from these conventions. + +\begin{itemize} + \item + All files in one directory. + \item + No two chapters in one file. A chapter macro should be located at + the beginning of a file. + \item + No nesting, i.e.\ no chapter or class definition within a class + defining environment. (The conventions impose a two-level file + hierarchy.) + \item + No two classes of the same name in one manual. +\end{itemize} + + +See Section~\ref{sectionHtmlExtended} for a new extended conversion +model using multiple directories to overcome the filename problem. +See Section~\ref{sectionHTMLsupport} how the file generation of class +environments could be customized with \verb+\ccHtmlNoClassFile+ and the +environment {\tt ccHtmlClassFile} to gain more flexibility. + +\index{title page} +By default, a \LaTeX\ file is assumed to start with a chapter macro or +a class defining environment. Any pieces of \LaTeX\ code in front of +it are most probably definitions and not meant for conversion. For +example a complete manual starts with a title page and the table of +contents. These are provided by other means for the online {\tt HTML} +manual, i.e.\ the title page {\tt title.html} has to be written +manually and the table of contents {\tt contents.html} is +automatically generated. In the case of a file without a chapter +macro or a class defining environment one would like to see the +conversion result for these parts too. To get it printed to stdout use +the command line switch {\tt -show\_main}, see below. + + +% ------------------------------------------------------- +\subsection{The Conversion Tools} + +The conversion of a specification to an online {\tt HTML} manual is a +two step process. In the first step, all \LaTeX\ files are converted +to {\tt HTML} files. Meanwhile auxiliary informations about +\Dindex{hyperlinks} are collected. In the second step, the hyperlinks +are added to all {\tt HTML} files. The {\tt csh}-script {\tt + cc\_manual\_to\_html} integrates the first and second step. It uses +the program {\tt cc\_extract\_html}, which does the first part, the +program {\tt flex}, which generates the filter program to add the +hyperlinks, the standard C compiler {\tt cc}, and the program {\tt + cc\_index\_sort}, which sorts the index in a manner that small and +capital letters are put together. The synopsis for the script {\tt + cc\_manual\_to\_html} is: + +\ind{\tt cc\_manual\_to\_html [] } + +This command translates all LaTeX files in its commandline to {\tt + HTML} files. All files included with the \verb+\input+ or +\verb+\include+ macros of \LaTeX\ are processed too. Please note that +the program {\em does not} understand the \verb+\includeonly+ macro. +The program is capable of translating a complete manual at once. It is +sufficient to use it with the main \LaTeX\ file. + +\index{bibliography}\TTindex{BiBTeX}\index{auxiliary file} +\Mindex{bibcite}\Mindex{bibitem} +The converter supports the generation of an {\tt HTML} file {\tt + biblio.html} for the bibliography. If the bibliography is generated +using BiB\TeX\ the {\tt *.bbl} file should provided to the converter. +If the bibliography is written by hand using the +\verb+thebibliography+ environment, this file should also be in the +list of conversion files. In both cases, the related {\tt *.aux} will +contain \verb+\bibcite+ entries that are needed to generate proper +labels instead of the internally used citation keys. However, if the +bibliography is written by hand with optional arguments in the bibitem +entries the {\tt *.aux} file is not necessary (These optional +arguments will be also used by \LaTeX\ to label the citations.). The +\verb+\+\verb+ref+ macros in \LaTeX\ will be instrumented with +\Dindex{hyperlinks} to the bibliography. A table of contents {\tt + contents.html} and an index {\tt manual\_index.html} are always +automatically generated. A handwritten title page {\tt title.html} is +assumed, but not supplied. A common page layout on all pages +guarentees easy navigation through the different files. + +The command line options for {\tt cc\_manual\_to\_html} are: + +\begin{tabular}{ll} + {\tt -defaults} & show the settings of the internal variables.\\ + {\tt -extended} & new extended conversion model, see + Section~\ref{sectionHtmlExtended} \\ + {\tt -show\_main} & print the translation result for the main + file to stdout.\\ + {\tt -date } & set a date for the manual. Default: system date.\\ + {\tt -release } & set a release number for the + manual. Default: empty\\ + {\tt -title } & set a title text for the manual.\\ + & Default: ``Reference Manual''.\\ + {\tt -author } & set an author address (email) for the manual. \\ + & Default: ``The \cgal\ Project''. \\ + {\tt -config } & path to the configuration files.\\ + {\tt -tmp } & temporary directory to keep all intermediate files.\\ + {\tt -header } & set the path where the C headers are.\\ + {\tt -o } & output directory for the generated {\tt HTML} manual.\\ + {\tt -aux } & \LaTeX\ auxiliary file with the + \verb+\bibcite+ entries.\\ + {\tt -bbl } & bibliography file produced by BiB\TeX.\\ + {\tt -sty