\message{Converted from GuideToTeX.guide by GuideToDVI, Copyright 1998 Frederic Delacroix, MAILWARE.} \magnification=\magstep0 \catcode`\@=11\hsize=16cm\vsize=24cm\hoffset=0mm\voffset=0mm \pretolerance=1000\tolerance=5000\brokenpenalty=7000 \hfuzz=1pt\hbadness=1000\overfullrule=2mm \parindent=0mm \def\^#1{\if#1i{\accent"5E\i}\else{\accent"5E #1}\fi} \def\"#1{\if#1i{\accent"7F\i}\else{\accent"7F #1}\fi} \catcode`\@=12 \newif\iftitlepage\titlepagefalse \newtoks\titlepagehead\titlepagehead={\hfil} \newtoks\titlepagefoot\titlepagefoot={\hfil} \newtoks\leftpagehead\leftpagehead={\hfil\tenrm\the\databasename/\the\currentnodetitle\hfil} \newtoks\leftpagefoot\leftpagefoot={\qquad\tenrm\folio\hfil} \newtoks\rightpagehead\rightpagehead={\hfil\tenrm\the\databasename/\the\currentnodetitle\hfil} \newtoks\rightpagefoot\rightpagefoot={\hfil\tenrm\folio\qquad} \headline={\iftitlepage\the\titlepagehead\else\ifodd\pageno\the\rightpagehead\else\the\leftpagehead\fi\fi} \footline={\iftitlepage\the\titlepagefoot\global\titlepagefalse\else\ifodd\pageno\the\rightpagefoot\else\the\leftpagefoot\fi\fi} \def\link#1{\underbar{#1}} \def\node#1#2{{\bf #1.--- #2}\medskip\nobreak\currentnodenumber=#1\currentnodetitle={#2}} \def\endnode{\smallskip\hrule\goodbreak\bigskip} \def\gobold{\bf{}} \def\goitalic{\it{}} \def\gounderline{\tt{}} \def\gounbold{\rm{}} \def\gounitalic{\rm{}} \def\goununderline{\rm{}} \def\blanklineskip{\medskip} \newtoks\databasename\databasename={GuideToTeX.guide} \newtoks\guidefilename\guidefilename={GuideToTeX.guide} \newtoks\guidedirname\guidedirname={} \newtoks\guidepath\guidepath={GuideToTeX.guide} \newtoks\guideabspath\guideabspath={D\'eveloppement:Progs/GuideToTeX/Doc/English/GuideToTeX.guide} \newcount\currentnodenumber\currentnodenumber=0 \newtoks\currentnodetitle\currentnodetitle={} \newif\ifauthordef\newif\ifguideversiondef\newif\ifcpyrghtdef\newif\ifmasterdef \authordeffalse\guideversiondeffalse\cpyrghtdeffalse\masterdeffalse \cpyrghtdeftrue \newtoks\cpyrght \cpyrght={Copyright $\copyright$1998 Fr\'ed\'eric Delacroix} \guideversiondeftrue \newtoks\guideversion \guideversion={GuideToTeX.guide 1.01 (27.10.98)} \authordeftrue \newtoks\author \author={Fr\'ed\'eric Delacroix} \message{TitlePage.tex 1.1 english, Copyright 1998 Frederic Delacroix, part of the GuideToTeX package} % Feel free to modify this file and distribute under a different name % Mail me your creations so that they're included with the next GuideToTeX % package! % Frederic.Delacroix@univ-valenciennes.fr %$VER: TitlePage 1.1 english (12.08.98) \font\TitleFont = cmcsc10 scaled \magstep5 \font\AuthorFont = cmssdc10 scaled \magstep2 \titlepagetrue \null\vfill {\centerline{\vbox{\hrule height 3pt depth 1pt\hbox{\vrule width 4pt \vbox spread 1cm{\vfill\hbox spread 1cm{\hfill{\TitleFont\the\databasename }\hfill}\vfill}% \vrule width 4pt}\hrule height 3pt depth 1pt}} } \ifauthordef\vskip 2cm\centerline{\AuthorFont by \the\author}\fi \vfill \ifguideversiondef\centerline{{\tenrm\the\guideversion}}\vskip 5mm\fi \ifcpyrghtdef\centerline{{\tenrm\the\cpyrght}}\vskip 1cm\fi \null\eject \null\vfill {\sevenrm Converted from the AmigaGuide file \the\guidefilename\ with GuideToTeX on {\oldstyle\the\day}/{\oldstyle\the\month}/{\oldstyle\the\year}.} \medskip {\sevenrm GuideToTeX \copyright\ {\oldstyle 1998} Fr\'ed\'eric Delacroix, MAILWARE.} \vskip 1cm\null \eject \node{1}{GuideToTeX Documentation} \blanklineskip This file describes \bf{}GuideToTeX 1.01\rm{}, a set of ARexx programs used to convert an AmigaGuide file into a TeX source file, suitable for typesetting with TeX and showing/printing via ShowDVI/DVIPrint (part of PasTeX). \blanklineskip \par\hskip 58mm{}TABLE OF CONTENTS \blanklineskip \par\hskip 16mm{}\link{Distribution and disclaimer} \par\hskip 16mm{}\link{Introduction} \par\hskip 16mm{}\link{System requirements} \blanklineskip \par\hskip 16mm{}\link{GuideToTeX.rexx} \par\hskip 16mm{}\link{GuideToDVI.rexx} \par\hskip 16mm{}\link{Provided headers} \par\hskip 16mm{}\link{FAQs and hints} \blanklineskip \par\hskip 16mm{}\link{History} \par\hskip 16mm{}\link{Known problems} \par\hskip 16mm{}\link{Credits} \par\hskip 16mm{}\link{Contacting the author} \endnode \node{2}{Distribution and disclaimer} This archive contains \bf{}GuideToTeX.rexx\rm{}, a program of mine to convert AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} files into TeX source files. \blanklineskip It is released as \it{}MAILWARE\rm{}, which means that: \blanklineskip --- You are allowed to distribute this piece of code \bf{}freely\rm{}, provided that \bf{}no alteration\rm{} is made to the archive and no profit is made from the distributions. Exceptions are Aminet CD and AmigaNews CD. \blanklineskip --- If you intend to distribute GuideToTex as part of a package that is not for free, you must first \link{contact} me. Basically, I'll ask for a free copy of the package in question. \blanklineskip --- No restriction is placed over the use of the files produced by GuideToTeX. \blanklineskip --- You may freely use this software, you are not required to pay me something. However, I would like to receive some mail so I ask you to drop \link{me} a note saying you find GuideToTeX useful. Of course I won't refuse gifts/money/A4000Ts :-) \blanklineskip --- Disclaimer: \blanklineskip \bf{}THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. \blanklineskip IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. \blanklineskip THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\rm{} \endnode \node{3}{Introduction} It all began when I tried to print an AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} file. As everyone knows, an AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} file is divided into nodes, which are not displayed all at the same time. They are linked together via links (surprise!) and the user is able to jump from one node to another by clicking on those links. \blanklineskip Such a structure is great for displaying a doc file on screen, but it becomes quite strange when sent to a printer, as all AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} commands which are normally hidden become visible. \blanklineskip I then thought of clearing by hand all those AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} commands, and to copy the contents of each node into a plain text file, with the help of the clipboard. But it was quite unhandy and became very long for large guides. \blanklineskip So I thought of a program to do the job. As ARexx has handy functions for manipulating strings and was easy to use, it was the best choice for quick development. Then I thought "why dropping such lovely AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} commands that could be used to enhance the printing of the file?". So I chose to convert the file to TeX format instead of plain ASCII text. \blanklineskip The tool texinfo already exists that can output (among other things like html) AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} files and DVI files, but requires the author writes the documentation in an even higher language. Programs you can find on Aminet (or elsewhere) generally only provide the AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} documentation files. Anyway, AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} files produced by texinfo are generally converted very well by GuideToTeX. \blanklineskip For those who don't know TeX, it is a portable typesetting system that is universally used for its high-quality typesetting (thanks to clever algorithms and vector fonts) and excellent handling of mathematics. TeX is not a WYSIWYG (What You See Is What You Get) system, it is a language: you first type a "source" document (an ASCII file that contains many commands, beginning with a "$\backslash$") and then process it through TeX to produce a "dvi" (device independent) file, which can then be displayed on screen or printed. \blanklineskip The best implementation of TeX on the Amiga (and the most up-to-date) is currently AmiWeb2c, by Andreas Scherer (who did the conversion from Unix to AmigaOS). It uses parts of PasTeX, the first public domain implementation of TeX on the Amiga. Aminet contains a whole directory for TeX-related files ("text/tex"). \blanklineskip So I wrote GuideToTeX as an ARexx program. Needless to say that my first thoughts of an "easy job of 1 hour" proved wrong. Indeed, many special cases were to be taken into account, as to links, styles, escaped characters, translating characters to TeX format... Anyway, here it is. It's not perfect (see \link{problems}) but it proved useful although the output file may require a bit of editing for top typesetting. \blanklineskip For an example of what it can do, see the \link{GuideToTeX.guide.dvi} file, it was produced from this file with very few editing. \blanklineskip Now, the GuideToTeX package has been divided in several parts. The heart of the system is the \link{GuideToTeX.rexx} ARexx script, which does all the conversion stuff. The program \link{GuideToDVI.rexx} adds more features and options at a higher level. And there are a number (well currently 1 :-) of \link{header files} for some adjustments. With a bit of experience, I am sure you will find this system quite powerful. Don't forget to tell me about it! \blanklineskip \endnode \node{4}{System requirements} GuideToTeX requires: \blanklineskip -- An Amiga (or maybe UAE) \blanklineskip -- Version 2.04 or higher of the AmigaOS is maybe necessary. I strongly suggest version 3.1 or higher. \blanklineskip -- ARexx running (make sure RexxMast is started in your startup-sequence or user-startup). \blanklineskip -- rexxdossupport.library $\copyright$1994-1997 Hartmut Goebel (the archive is provided). \blanklineskip -- AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} files to convert :-) \blanklineskip -- a TeX package will be necessary for typesetting the resulting TeX files. Search for "AmiWeb2C" on Aminet. \blanklineskip -- a bit of knowledge and TeXnique may be required to adjust the results. \blanklineskip -- if you want to use the graphical interface GuideToDVI-GUI, you need Argue version 0.9 or higher. It is a MUI interface systems for programs using ReadArgs(). You will find it on Aminet. Argue was written and copyrighted by Thorsten "Flavour" Stocksmeier. \endnode \node{5}{GuideToTeX.rexx} GuideToTeX.rexx is the script the GuideToTeX package is based upon. It takes care of the conversion of most AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} commands into their TeX "equivalents". Several other scripts call GuideToTeX.rexx but provide higher level options. \blanklineskip From the shell, usage is as follows: \blanklineskip rx GuideToTeX.rexx GUIDEFILE/A, PRE= PREINCLUDE/K, POST= POSTINCLUDE/K, LINKTOKENS/K, NODETOKENS/K, ENDNODETOKENS/K, B=BOLD/K, UB= UNBOLD/K, I= ITALIC/K, UI= UNITALIC/K, U= UNDERLINE/K, UU= UNUNDERLINE/K, SPACEINDENT/K/N, TABINDENT/K/N, RUNTEX/K, NOACCENTS/S, ONLYNODES/S, BLS=BLANKLINESKIP/K, LOGFILE/K, QUIET/S \blanklineskip For those who are not familiar with the syntax of the ReadArgs() function, read \link{here} for the meaning of the /$<$letter$>$: \blanklineskip \bf{}GUIDEFILE\rm{} : (required) the name of the guide file to be converted. The output file will be the same but with a ".tex" extension. \blanklineskip \bf{}PRE=PREINCLUDE\rm{} : The name of a TeX file to be included before any text is processed. This should include font definitions and any special macro needed for LINKTOKENS or NODETOKENS, and any text needed before the contents of the guide are included. Default is no file. \blanklineskip \bf{}POST=POSTINCLUDE\rm{} : The name of a TeX file to be included after all the text in the guide file has been processed. Default is no file. \blanklineskip \bf{}LINKTOKENS\rm{} : The tokens to include when a link is encountered in the file. For example, if LINKTOKENS is set to "$\{\backslash$bf \%s$\}$" then the links will appear in bold. The default is "$\backslash$underbar$\{$\%s$\}$" which will underline the links. The "\%s" denotes where the link text will be placed. \blanklineskip \bf{}NODETOKENS\rm{} : The tokens to include when a new node is encountered. Then "\%s" denotes the title of the node (defaults to the node name if there is no title to the node) and \%d denotes the number of the node (starting from 1). This can be used to build section titles as: "$\backslash$vskip 1cm $\{\backslash$headingfont \%d.--- \%s$\}$". Use NODETOKENS="" if you don't want the titles. You could also use a page jump ($\backslash$vfill$\backslash$eject). The default is "$\{\backslash$bf \%d.--- \%s$\}\backslash$medskip$\backslash$nobreak" which causes a the number and title of the node separated by an em dash and printed in bold, and a medium skip, with no page break. \blanklineskip \bf{}ENDNODETOKENS\rm{} : The tokens to include when an end of node is reached. These are inserted "as is", i.e. no "\%s" stuff is done. The default is "smallskiphrulegoodbreakbigskip": a vertical skip, horizontal rule, indication of a possible page break and another vertical blank. \blanklineskip \bf{}B=BOLD\rm{} : The AmigaGuide command @$\{$b$\}$ will translate to this. Default: $\backslash$bf$\{\}$. \blanklineskip \bf{}UB=UNBOLD\rm{} : The AmigaGuide command @$\{$ub$\}$ will translate to this. Default: $\backslash$rm$\{\}$. \blanklineskip \bf{}I=ITALIC\rm{} : The AmigaGuide command @$\{$i$\}$ will translate to this. Default: $\backslash$it$\{\}$. \blanklineskip \bf{}UI=UNITALIC\rm{} : The AmigaGuide command @$\{$ui$\}$ will translate to this. Default: $\backslash$rm$\{\}$. \blanklineskip \bf{}U=UNDERLINE\rm{} : The AmigaGuide command @$\{$u$\}$ will translate to this. Default: $\backslash$tt$\{\}$. \blanklineskip \bf{}UU=UNUNDERLINE\rm{} : The AmigaGuide command @$\{$uu$\}$ will translate to this. Default: $\backslash$rm$\{\}$. \blanklineskip \bf{}SPACEINDENT\rm{} : If a line is indented with spaces, the spaces are replaced by a $\backslash$hskip causing a horizontal blank. The amount of that skip is the number of spaces indenting the line times the value expressed here in millimeters. The default is 2 millimeters. \blanklineskip \bf{}TABINDENT\rm{} : If a line is indented with tabulators, they are replaced by a $\backslash$hskip causing a horizontal blank. The amount of that skip is the number of tabulators indenting the line times the value expressed here in millimeters. The default is 16 millimeters, causing the (default) tabulator to be equivalent to eight (default) spaces. \blanklineskip \bf{}RUNTEX\rm{} : If this argument is not empty (default) then it is used as an invocation command for typesetting. Suggested is simply "tex \%s". The "\%s" will of course be replaced by the destination file name. \blanklineskip \bf{}NOACCENTS\rm{} : If you know your guide file does not contain accented characters, or if you use a eight-bit version of TeX, you can disable the conversion of accented (and other) characters (\`a,\'e,\`e,\~N,$\times$,etc.) with this switch. This will speed up the conversion. \blanklineskip \bf{}ONLYNODES\rm{} : Normally, text which happens not to be in a node (ie between a @node/@endnode pair) is processed all the same, although it is not visible in the guide. With this switch set, GuideToTeX will ignore such text. \blanklineskip \bf{}BLS=BLANKLINESKIP\rm{} : If a blank line is detected, this macro is inserted. This is by default "$\backslash$medskip" but you can change it as you wish. Note however that a blank line also implies the end of a paragraph and that TeX then adds the $\backslash$parskip vertical blank before the new paragraph. This macro is useful if a paragraph is started by TeX because of an indented line but no blank line in the guide: this macro is NOT included in that case. \blanklineskip \bf{}LOGFILE\rm{} : Name of a file which will contain all outputs of GuideToTeX. It is not affected by the QUIET option. Default: "GuideToTeX.log". \blanklineskip \bf{}QUIET\rm{} : Only display error messages. \blanklineskip Don't forget to read about the \link{problems}! \endnode \node{6}{GuideToDVI.rexx} GuideToDVI.rexx is a script that uses GuideToTeX.rexx but provides higher level options for the conversion. Basically, GuideToDVI.rexx prepares a temporary file containing useful macro definitions and tokens definitions used for the conversion, along with some adjustments for a better page layout. \blanklineskip GuideToDVI.rexx is used from the shell and called like this: \blanklineskip rx GuideToDVI.rexx GUIDEFILE/A, CONFIG/K, MAGNIFICATION/K/N, HSIZE/K/N, VSIZE/K/N, HOFFSET/K/N, VOFFSET/K/N, BLACKBOXES/S, PARINDENT/K/N, FRENCH/S, TPH= TITLEPAGEHEAD/K, TPF= TITLEPAGEFOOT/K, LPH= LEFTPAGEHEAD/K, LPF= LEFTPAGEFOOT/K, RPH= RIGHTPAGEHEAD/K, RPF= RIGHTPAGEFOOT/K, PRE= PREINCLUDE/K, POST= POSTINCLUDE/K, LOGFILE/K, QUIET/S \blanklineskip All those arguments can also be filled via a MUI GUI by double-clicking on GuideToDVI-GUI. You \link{need} Argue for this. \blanklineskip For those who are not familiar with the syntax of the ReadArgs() function, read \link{here} for the meaning of the /$<$letter$>$: \blanklineskip Before going on with the description of each argument, note that each of these can also be found in a configuration file (specified by the \bf{}CONFIG\rm{} keyword). Arguments on the command line override those in the configuration file. The default configuration file is \it{}"TEX:config/GuideToDVI.config"\rm{}. \blanklineskip \bf{}GUIDEFILE\rm{} : (required) the name of the guide file to be converted. \blanklineskip \bf{}CONFIGFILE \rm{} : name of a config file to read. Config files contain the same commands, except for \bf{}GUIDEFILE\rm{}. Default: "TEX:config/GuideToDVI.config". \blanklineskip \bf{}MAGNIFICATION\rm{} : magnification factor for the document. Default: 0. \blanklineskip \bf{}HSIZE\rm{} : page width, in centimeters. Default: 16. \blanklineskip \bf{}VSIZE\rm{} : page height, in centimeters. Default: 24. \blanklineskip \bf{}HOFFSET\rm{} : text horizontal offset in the page, in millimeters. Default:0. \blanklineskip \bf{}VOFFSET\rm{} : text vertical offset in the page, in millimeters. Default:0. \blanklineskip \bf{}BLACKBOXES\rm{} : (use BLACKBOXES on|off). Enables or disables TeX's black boxes in the right margin where there are overfull $\backslash$hboxes. Default: off. \blanklineskip \bf{}PARINDENT\rm{} : Paragraph indention, in millimeters. Default: 0. \blanklineskip \bf{}FRENCH\rm{} : Toggles the french style. This implies $\backslash$frenchspacing and the redefinition of punctuation signs to take into account the french rules for those. Default: off. \blanklineskip \bf{}TPH=TITLEPAGEHEAD\rm{} : The tokens to insert in the headline of the title page (normally the first page of the document). Default: "$\{\backslash$hfil$\}$". \blanklineskip \bf{}TPF=TITLEPAGEFOOT\rm{} : The tokens to insert in the footline of the title page (normally the first page of the document). Default: "$\{\backslash$hfil$\}$". \blanklineskip \bf{}LPH=LEFTPAGEHEAD\rm{} : The tokens to insert in the headline of the left (even) page. Default: "$\{\backslash$hfil$\backslash$tenrm$\backslash$the$\backslash$databasename/$\backslash$the$\backslash$currentnodetitle$\backslash$hfil$\}$". \blanklineskip \bf{}LPF=LEFTPAGEFOOT\rm{} : The tokens to insert in the footline of the left (even) page. Default: "$\{\backslash$hfil$\backslash$tenrm$\backslash$folio$\backslash$hfil$\}$". \blanklineskip \bf{}RPH=RIGHTPAGEHEAD\rm{} : The tokens to insert in the headline of the right (odd) page. Default: same as \bf{}LPH\rm{}. \blanklineskip \bf{}RPF=RIGHTPAGEFOOT\rm{} : The tokens to insert in the footline of the right (odd) page. Default: same as \bf{}LPF\rm{}. \blanklineskip \bf{}PRE=PREINCLUDE\rm{} : Name of a TeX file to be included before the text of the guide. Default: "" (none). \blanklineskip \bf{}POST=POSTINCLUDE\rm{} : Name of a TeX file to be included after the text of the guide. Default: "" (none). \blanklineskip \bf{}LOGFILE\rm{} : Name of a file which will contain all outputs of GuideToDVI. It is not affected by the QUIET option. Default: "GuideToDVI.log". \blanklineskip \bf{}QUIET\rm{} : only display error messages. It implies QUIET for \link{GuideToTeX.rexx} too. \blanklineskip After processing by GuideToDVI.rexx, the file is processed through TeX via the command \it{}tex \%s\rm{} (\%s is replaced by the converted file name). \blanklineskip \blanklineskip You need some TeX knowledge to modify the following values and macros. The default settings should be OK for the novice user. \blanklineskip Some special tokens or counters are defined (in the temporary file created by GuideToDVI) and can safely be used in a redefinition of the \bf{}$\backslash$link\rm{}, \bf{}$\backslash$node\rm{} or \bf{}$\backslash$endnode\rm{} macros (read on for more about these), or used in a \bf{}PREINCLUDE\rm{} or \bf{}POSTINCLUDE\rm{} file. They are NOT macros themselves, you must use $\backslash$the to include them in the text. \blanklineskip \bf{}$\backslash$databasename\rm{} : Name of the database (after the @database keyword at the begining of the guide). \blanklineskip \bf{}$\backslash$guidefilename\rm{} : Name of the guide file. This can differ from \bf{}$\backslash$databasename\rm{}, of course. Only the file component of the path. \blanklineskip \bf{}$\backslash$guidedirname\rm{} : Name of the directory containing the guide file. This is NOT an absolute path, rather the path component of the \bf{}GUIDEFILE\rm{} argument. \blanklineskip \bf{}$\backslash$guidepath\rm{} : Path of the guide file, as given on the command line. \blanklineskip \bf{}$\backslash$guideabspath\rm{} : Absolute path of the guide. \blanklineskip \bf{}$\backslash$currentnodenumber\rm{} : This is a counter containing the node number. Set by the default \bf{}$\backslash$node\rm{} macro. \blanklineskip \bf{}$\backslash$currentnodetitle\rm{} : Title of the current node. Set by the default $\backslash$node macro. \blanklineskip \bf{}$\backslash$titlepagehead\rm{}, \bf{}$\backslash$titlepagefoot\rm{}, \bf{}$\backslash$leftpagehead\rm{}, \bf{}$\backslash$leftpagefoot\rm{}, \bf{}$\backslash$rightpagehead\rm{}, \bf{}$\backslash$rightpagefoot\rm{} : contain the tokens corresponding to the arguments with the same names. \blanklineskip \bf{}$\backslash$titlepage\rm{} is a new if. Set \bf{}$\backslash$titlepagetrue\rm{} if you want a page to be considered as a title page (that is \bf{}$\backslash$titlepagehead\rm{} and \bf{}$\backslash$titlepagefoot\rm{} will be inserted in place of \bf{}$\backslash$left(right)pagehead\rm{} and \bf{}$\backslash$left(right)pagefoot)\rm{}. This remains active only for one page and is false (\bf{}$\backslash$titlepagefalse\rm{}) by default. \blanklineskip \bf{}$\backslash$authordef\rm{} is a new if. It is true ($\backslash$authordeftrue) if a @author command has been found in the guide, in which case the \bf{}$\backslash$author\rm{} token is defined. \blanklineskip \bf{}$\backslash$author\rm{} contains the name of the author of the guide, if \bf{}$\backslash$authordef\rm{} is true (test it with a command like \it{}"$\backslash$ifauthordef author:$\backslash$the$\backslash$author$\backslash$else unknown author"\rm{}). \blanklineskip \bf{}$\backslash$guideversiondef\rm{} is a new if which is true if a @\$VER: command has been found in the guide, in which case \bf{}$\backslash$guideversion\rm{} is defined. \blanklineskip \bf{}$\backslash$guideversion\rm{} contains the version message of the guide. Only valid if \bf{}$\backslash$guideversiondef\rm{} is true (see $\backslash$author above). \blanklineskip \bf{}$\backslash$cpyrghtdef\rm{} is a new if set to true if a @(c) command was found in the guide, in which case \bf{}$\backslash$cpyrght\rm{} is defined. \blanklineskip \bf{}$\backslash$cpyrght\rm{} contains the copyright message of the guide, if defined (i.e. \bf{}$\backslash$cpyrghtdef\rm{} is true). Make the difference between $\backslash$copyright (the $\copyright$ sign, in TeX) and this token. \blanklineskip \bf{}$\backslash$masterdef\rm{} is a new if, true if the @master command was found in the guide. In that case, \bf{}$\backslash$master\rm{} is defined. \blanklineskip \bf{}$\backslash$master\rm{} contains the name of the file used for the creation of the guide. Rarely used in practice. Only valid if \bf{}$\backslash$masterdef\rm{} is true. \blanklineskip \blanklineskip Finally, those macros are used, you can redefine them in a \bf{}PREINCLUDE\rm{} file for a different look of the converted file: \blanklineskip \bf{}$\backslash$link\#1\rm{} : This is the macro called for each link found. The argument \#1 is the text of the link. The default is $\backslash$underbar$\{$\#1$\}$ (underlines the link). \blanklineskip \bf{}$\backslash$node\#1\#2\rm{} : This is the macro called when a new node is encountered. The arguments \#1 and \#2 are respectively the number of the node and its title. The default is $\{\backslash$bf \#1.--- \#2$\}\backslash$medskip$\backslash$nobreak$\backslash$currentnodenumber=\#1 $\backslash$currentnodetitle=$\{$\#2$\}$ (prints in bold the node number, a dot, an em dash, the node title, skips a medium vertical space, prevents a page break, and sets the \bf{}$\backslash$currentnodenumber\rm{} and \bf{}$\backslash$currentnodetitle\rm{} values). Remember to set these last two tokens if you use them elsewhere (e.g. in the head/footline of a page). \blanklineskip \bf{}$\backslash$endnode\rm{} : This is the macro called when the end of a node is reached. The default is $\backslash$smallskip$\backslash$hrule$\backslash$goodbreak$\backslash$bigskip which does a small vertical skip, draws a horizontal line, indicates the possibility of a page break and does a big vertical skip. \blanklineskip \bf{}$\backslash$gobold\rm{}, \bf{}$\backslash$gounbold\rm{}, \bf{}$\backslash$goitalic\rm{}, \bf{}$\backslash$gounitalic\rm{}, \bf{}$\backslash$gounderline\rm{}, \bf{}$\backslash$goununderline\rm{} are macros called when a style change is required. See \link{GuideToTeX.rexx} for the default values. They are there for an easy redefinition, they are not really used by GuideToDVI.rexx, rather by \link{GuideToTeX.rexx}. \blanklineskip \bf{}$\backslash$blanklineskip\rm{} : this macro is inserted when a blank line is detected in the guide. See \link{GuideToTeX.rexx} for a description, as this macro is used as the \bf{}BLANKLINESKIP\rm{} argument for \link{GuideToTeX.rexx}. The default value is $\backslash$medskip. \endnode \node{7}{ReadArgs() conventions} \bf{}/A\rm{} denotes a mandatory argument. If it is not given, the program will fail. \blanklineskip \bf{}/K\rm{} indicates that the keyword must be explicitely specified for the argument to be recognized. You can use a space or an = sign between the keyword and the argument. \blanklineskip \bf{}/N\rm{} says that the argument must be a number. \blanklineskip \bf{}/S\rm{} says the argument is a switch: either it is present or it is not. \blanklineskip \bf{}/T\rm{} says the argument is a toggle. You can use either the argument name to flip the swich on or off or use the name followed by on or off. This way an argument may be set several times (on the command line or a config file). \blanklineskip \tt{}Note\rm{} : The ARexx implementation of ReadArgs() is in the rexxdossupport.library by Hartmut Goebel. Great work, Hartmut. \endnode \node{8}{Provided header files} This release of GuideToTeX contains only two header files. Hopefully there will be more in the future. If you write interesting ones, send them to \link{me} so that I can include them in the next release. \blanklineskip Headers are used with the \bf{}PREINCLUDE\rm{} option of either \link{GuideToTeX.rexx} or \link{GuideToDVI.rexx}. They add further features for the layout. \blanklineskip \it{}TitlePage.tex\rm{}: \par\hskip 16mm{}This file is my first attempt at creating an automatic title page generator. Use it (only) with \link{GuideToDVI.rexx}: \blanklineskip \it{}RX GuideToDVI $<$AmigaGuidefile$>$ PRE TitlePage.tex\rm{} \blanklineskip This will result in a title page being created with the database name in a box in the middle of the page, and author, copyright and version information if defined (see \link{GuideToDVI}), a blank page right after it. Try it. \blanklineskip \it{}BoxLinks.tex\rm{} \par\hskip 16mm{}This renders links as boxes (just like in Multiview) instead of underlining them. The printed result is not that good, that's why I did not make it the default. But if you like it, use it as the \bf{}PRE\rm{} argument in \link{GuideToDVI}. \endnode \node{9}{FAQs and hints} In this section, I've put some hints and FAQs about the conversion and typesetting via GuideToTeX of an AmigaGuide\raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} file. If you have further problems not listed here or in \link{known problems}, mail \link{me}. \blanklineskip \it{}When typesetting, TeX complains about many overfull boxes and there are black boxes in the right margin.\rm{} \blanklineskip \par\hskip 16mm{}This is not the fault of GuideToTeX, rather that of TeX, which is kind of picky about a line running into the right margin. The solution is to reformat the guide file and add spaces where you can tolerate a line break. If this still isn't sufficient, you may have to edit the TeX file to instruct manually what to do to TeX. \par\hskip 16mm{}If the overfull amount is small and you can tolerate it, you may ignore the message and use the \bf{}BLACKBOXES off\rm{} option of \link{GuideToDVI.rexx}. Or you can increase the tolerance of TeX by modifying the \it{}$\backslash$hfuzz\rm{} value (which is set at the beginning of the document to 1pt by \link{GuideToDVI.rexx} (not \link{GuideToTeX.rexx}!). If this still isn't enough, you can insert some \it{}$\backslash$goodbreak\rm{} macros where the lines can be broken, or maybe a \it{}$\backslash$raggedright\rm{} to tell TeX to abandon the right justification. \blanklineskip \blanklineskip \it{}What should I do with underfull boxes?\rm{} \blanklineskip \par\hskip 16mm{}Ignore them, in most cases. \blanklineskip \blanklineskip \it{}I get messages "warning, untranslated non-ASCII character". What should I do?\rm{} \blanklineskip \par\hskip 16mm{}TeX only works with \bf{}ASCII\rm{} characters (ie whose code is between 0 and 127) as the other ones (128-255) are not completely standard. GuideToTeX does its best to convert \bf{}Latin-1\rm{} characters (such as those used by the Amiga, Unix, and er... Widnoze? Whats the name of that DOS-GUI again? :-) ) to valid TeX macros, but this is not always possible. It is easy to do so for accented letters, I did not always find a equivalent for the others. One of the hardest ones was the "registered" logo \raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$}, but the result is quite good I think. Currently, supported characters are: \blanklineskip \`A \'A \^A \~A \"A \^A \AE \c C \`E \'E \^E \"E \`I \'I \^I \"I \~N \`O \'O \^O \~O \"O \`U \'U \^U \"U \'Y \ss \`a \'a \^a \~a \"a \aa \ae \c c \`e \'e \^e \"e \`i \'i \^i \"i \~n \`o \'o \^o \~o \"o $\div$ $\phi$ \`u \'u \^u \"u \'y \"y $\times$ $\emptyset$ ~ !` $\copyright$ \leavevmode\raise.3ex\hbox{$\scriptscriptstyle\langle\!\langle$} \leavevmode\raise.3ex\hbox{$\scriptscriptstyle\,\rangle\!\rangle$} $\neg$ $-$ ${}^o$ $\pm$ ${}^2$ ${}^3$ $\mu$ \P $\bullet$ , ${}^1$ $\scriptscriptstyle {1\over4}$ $\scriptscriptstyle {1\over2}$ $\scriptscriptstyle {3\over4}$ ?` \raise 1ex\hbox{\rlap{$\,$\fiverm R}$\scriptstyle\bigcirc$} \blanklineskip If you have suggestions for the other ones, let \link{me} know so I can update the translation routine. In the meantime, when GuideToTeX encounters an untranslatable character, it warns the user and includes the character "as is" in the TeX file. Most of the time, unless you use a 8-bit version of TeX (most are nowadays) AND the involved character is defined as a macro, it is ignored by TeX's typesetting algorithm. \blanklineskip \par\hskip 16mm{}If you know your guide file does only contain pure ASCII characters, you can disable the translation routine in \link{GuideToTeX.rexx} with the \bf{}NOACCENTS\rm{} keyword. This is not possible for \link{GuideToDVI.rexx} for now, \link{let me know} if it is a problem. \blanklineskip \blanklineskip \it{}How can I include several header or post-include files?\rm{} \blanklineskip \par\hskip 16mm{}This is only possible for \link{GuideToDVI.rexx}. You must edit the configuration file and add a line with the \bf{}PREINCLUDE\rm{} (or \bf{}POSTINCLUDE\rm{}) argument and the corresponding file name. You can put as many as you wish, but always on a different line. Be warned that you can put only one on the command line. \blanklineskip \blanklineskip \it{}"Manually" underlined section titles appear strangely in the TeX file...\rm{} \blanklineskip \par\hskip 16mm{}Many people use a row of dashes or asterisks or other strange characters to underline or draw a box around important text. Unfortunately there is no real means to track this and, even if GuideToTeX will gladly convert those characters, the result in TeX won't be as good as expected, as TeX treats carriage returns as spaces. Even with an obeylines macro, be sure that ASCII art and TeX don't go well together. Then again, neither do ASCII art and proportionnal fonts. The only thing to do is to manually remove those underliners from the TeX source before re-typesetting. \endnode \node{10}{History} \tt{}Version 1.01 (27.10.98)\rm{} \par\hskip 16mm{}Fixed the way \^\ and \~\ are converted. It should work now (reported by Himanshu Gohel). \par\hskip 16mm{}A space was missing after the conversion of \aa and \^A. \par\hskip 16mm{}Updated the FAQs. \par\hskip 16mm{}Updated my e-mail address. \blanklineskip \tt{}Version 1.0 (10.08.98)\rm{} \par\hskip 16mm{}Added an empty group $\{\}$ after an hskip command so that indented lines begining with "plus" aren't misinterpreted. \par\hskip 16mm{}Modified the way inclusions are made in GuideToDVI.rexx: line $\backslash$input instead of a brutal inclusion, but the file management in TeX is so lousy that it couldn't find half of the files. I reverted to the "brutal" way. It works :-). \par\hskip 16mm{}Now a kludge in the GuideToDVI configuration file reading routine allows for several PRE/POST arguments, although ReadArgs() does not allow /K/M. Note however that you MUST write each such argument on a different configuration file line. \par\hskip 16mm{}The commands @author, @\$ver:, @(c), @master are now known. \par\hskip 16mm{}Added an Argue GUI for GuideToDVI.rexx. \blanklineskip \tt{}Version 1.0 beta (03.08.98)\rm{} \par\hskip 16mm{}First internal version. \endnode \node{11}{Known problems} This is a list of known problems. Work is on the way to correct them. \blanklineskip --- Problems with mixed styles: unbold also cancels italic and so on. However this could be fixed by the use of a bit of TeX conditionnal programming. I'll think of it. \blanklineskip --- Some guides use a non-zero left margin, which cause a new paragraph in the TeX file. In future versions I might add a workaround for this, with maybe a real support for hanging indentation. \blanklineskip --- Still there are some AmigaGuide commands that could be exploited, but I had to begin somewhere. \blanklineskip --- No real index support. This would be \bf{}VERY\rm{} hard to implement. :-) \blanklineskip --- It's slow. Yes I know it. When I have some time I \bf{}might\rm{} work out a compiled version! \blanklineskip If you discover bugs or would like enhancements, \link{mail} me!! \endnode \node{12}{Contacting the author} For everything about Amiga, Maths, bug reports, or a little chat, do not hesitate to mail me: \blanklineskip \tt{}e-mail\rm{}: Frederic.Delacroix@univ-valenciennes.fr \blanklineskip \tt{}Snail-mail\rm{}: \par\hskip 16mm{}Fr\'ed\'eric Delacroix \par\hskip 16mm{}4 rue Mirland \par\hskip 16mm{}59300 Valenciennes \par\hskip 16mm{}France. \blanklineskip GuideToTeX was written and tested on an A1200 equipped with a Blizzard 1230IV SCSI-2 turbo board, a 405Mb IDE HD and 8Mb of FAST memory. Being an ARexx program, I really see no reason why it should fail due to another configuration... unless you use Widows, of course :-) \endnode \node{13}{Credits and thanks} I wish to greet and thank the following people in no special order: \blanklineskip \par\hskip 16mm{}\it{}Hartmut Goebel\rm{} for the rexxdossupport.library. \blanklineskip \par\hskip 16mm{}\it{}Thorsten "Flavour" Stocksmeier\rm{} for Argue. \blanklineskip \par\hskip 16mm{}\it{}Andreas Scherer\rm{} for the wonderful AmiWeb2C. \blanklineskip \par\hskip 16mm{}\it{}William S. Hawes\rm{} for ARexx. \blanklineskip \par\hskip 16mm{}\it{}Guido Mersmann\rm{} for BoulderD\"ash. \blanklineskip \par\hskip 16mm{}\it{}The memory of Jay Miner\rm{} for the Amiga. \blanklineskip \par\hskip 16mm{}\it{}Himanshu Gohel\rm{} for the bug report. \blanklineskip \par\hskip 16mm{}\it{}All of the Amiga community\rm{} for continued support in these tough times. \endnode \bye % File converted from AmigaGuide by GuideToTeX % GuideToTeX Copyright 1998 Frederic Delacroix, FREEWARE %