\cgidef{ -tex -mail -f manpage.def}
%++++++++
%.IDENTIFICATION cgiprint.tex
%.PURPOSE        Man page of cgiprint, can be edited in LaTeX
%.AUTHOR         Francois Ochsenbein
%.VERSION   1.0  18-Mar-1993
%.VERSION   2.0  05-Dec-2005 (english)
%----------

%%% The following is ignored in htx context
\def\Beg#1#2{\begin{#1}}
\def\End#1{\end{#1}}

\def\pgm{{\bf cgiprint}\ }
\def\magic{{\tt\b cgidef\{}}
\def\Atag{{\em  entit\'e tagg\'ee} }
\def\Atags{{\em  entit\'es tagg\'ees} }
\def\atexte{{\em texte ``cliquable''}}
\ifhtx\def\secname#1{{\bf\fg{firebrick}#1}}\else\def\secname#1{{\sc #1}}\fi
\begin{manpage} {1}{cgiprint}{ Convert a text into HTML }
	{Dec. 2011}{HTML}
\def\pfile{{\em file}}\def\cols{{\em cols} }

\syntax{ \pgm 
	[{\bf--\%{\em letter}}] 
	[{\bf--bib}] 
	[{\bf--cat}] 
	[{\bf--D}macro=definition] 
	[{\bf--f} {\em tag\_file}] 
	[{\bf--glu}] 
	[{\bf--HELP}] 
	[{\bf--html}] 
	[{\bf--ic}] 
	[{\bf--keep[\^{ }\_\$\~{ }]} 
	[{\bf--lang} {\em language}] 
	[{\bf--lis}] 
	[{\bf--LIST}] 
	[{\bf--mail}] 
	[{\bf--n} {\em name}] 
	[{\bf--nomath}] 
	[{\bf--nooutput}] 
	[{\bf--oglu}
	[{\bf--o} {\em output\_program}] 
	[{\bf--pre}] 
	[{\bf--sec}] 
	[{\bf--tex}] 
	[{\bf--tex2}] 
	[{\bf--tag} {\em tag\_prefix}] 
	[{\bf--v\#\#}] 
	{\em input\_file}... }

\mansec{ Description }
\pgm\ is a filter which translates a text (from a set of files, 
or from the {\em standard input}) into HTML. The generated HTML
contains links {\em(anchors)}
as http addresses or {\em GLU} tags (http://simbad.u-strasbg.fr/glu/glu.html)
with the {\bf--glu} option. These links are either constructed from \Atags
having the generic form {\tt $<${\em nom\_tag}{\bf:}{\em valeur}$>$},
or from an interpretation of the text.

If the name of this program starts by {\bf Show} {\em(e.g. by creating a link
named {\tt Show-text} to \pgm)}, it can then be called directly by
the {\bf httpd}(1) daemon.

A few examples of \Atag: 
{\tt$<$Uni:{\em unit\_symbol}$>$},
an entity-GLU tag ({\tt$<$\%{\em type} {\em value}$>$}), 
or an action-GLU tag ({\tt$<$\&{\em action} {\em value}$>$}).
A {\em BibCode}, bibliographical reference made of 
19 characters {\tt YYYYJJJJJvvvvMppppA},
can typically be recognized automatically.

The text to convert can be in {\em TeX} form (with the {\bf--tex} option),
in a {\em TeX-light} form which contains only basic TeX macros and is
used for the abstracts (with the {\bf--tex2} option),
or can be in HTML  (with the {\bf--html} option); it can alos be
a mixture of latex/HTML with e.g. the text between
\b begin\{HTML\} and \b end\{HTML\} markers written in HTML.

\pgm\ also permits the substitution of environment variables,
either via the TeX macro {\tt\b env\{...\}} (in a TeX context),
or with the usage of the {\tt\$} sign (in a HTML context).
It should be notieced thatn as in a shell, the braces
{\bf\{ \}} can be used to delimit the variable's name, as in
{\tt\$\{var\}1}.

\mansec{ Usage }
All definitions --- the format of the input text, the definition
of the macros, how to convert \Atags into GLU or HTML markers, etc... ---
can be included in a {\em tag\_file} file, or included in the beginning
of the input text if it starts by {\bf\magic}

\mansec{Options}
\option{\bf--\%{\em letter}}
    asks to desactivate the automatic recognition of lines startin by
    {\tt\%-}{\em letter}.
    For instance, {\bf\tt-\%R} does not generate an anchor for the line\\
    {\tt \%R 1996ApJS..123.1234A} \\
    lorsque la reconnaissance automatique des bibcodes est active.
\option{\bf--bib | -+bib} 
    asks to transform the {\em BibCodes} embedded in the input text
    into anchors or GLU tags (the option  {\bf -+bib} removes this feature).
    Note that the {\em bibCode} has to be written in its canonical form
    (19 characters) to be recognized, and must be separated from the
    preceding and following text  by a blank or non-ambiguous punctuation
    characters like comma, bracket, ...
    Such bibcodes are interpretated as if these were written as \Atags
    {\tt $<$Bib:{\em bibcode}$>$}
     or 
    ou {\tt $<$\%R {\em bibcode}$>$} (--glu)
\option{\bf--cat | -+cat} 
    asks to recognized the {\em CatCodes} --- codes
    designating astronomical catalogues like {\bf III/123} or
    {\bf J/A+AS/112/234}
    (the {\bf -+cat} option disables this recognition).
    These {\em CatCodes} are interpretated as if these were written as \Atags
    {\tt $<$Cat:{\em CatCode}$>$} or
    {\tt $<$\%E {\em bibcode}$>$} (--glu)
\option{\bf--D{\em macro}={\em definition} }
    is meant to add macro definition(s) on the command line.
    Notice that the definition must be attached to the {\bf--D} symbol
    (as for pre-processor instructions in {\bf C} compiler);
    the leading {\tt\b} backslash may be omitted, and for instance
    {\tt -DmyURL=http://myhost} and {\tt -D'\b myURL=http://myhost'}
    are equivalent.
\option{\bf--f {\em tag\_file} }
    indicates a file which contains definitions.
    See below the \secname{tag\_file} section for details.
\option{\bf--HELP} 
    gives a list of options, and the list of all TeX macros recognized.
\option{\bf--html | -+html} 
    indicates that the input text contains HTML tags
    --- for instance things like {\tt$<$B$>$bold~text$<$/B$>$}
    (the {\bf -+html} option disables this recognition).
    The list of the acceptable ``tags'' are given in the {\em tag\_file}
    (see  \secname{tag\_file} section), while the non-recognized tags
    are transformed: as an example, the text
    {\tt Search for quasars in range  $2<z<3$} \\
    is (correctly) transformed into \\
    {\tt Search for quasars in range  $2\&lt;z\&lt;3$}

    Note: an HTML tag is not recognized as proper HTML syntax (and hence
    the $<$ is translated into {\tt\&lt;}) if:
    \begin{itemize}
    \item the closing {\tt$>$} is not on the same line as the opening {\tt$<$}
    \item the first word (followed by a space) which immediately follows the
	{\tt$<$} is not formed of letters all uppercase or lowercase.
	For exampl:\\
	{\tt$<$FONT {\em texte...}$>$} \\
	is recognized as an HTML tag, while \\
	{\tt$<$Font {\em texte...}$>$} \\
	is converted into {\tt\&lt;Font {\em texte...}\&gt;}
    \end{itemize}
\option{\bf--ic} 
	asks to ignore the input comments; by default the input comments
	are translated into HTML comments.
\option{\bf--keep[\^{ }\_\$\~{ }\%]}
	asks to consider the characters enumerated as {\em normal}
	characters; otherwise the characters indicate the modes
	{\em exponent}, {\em indice}, {\em mathematical}, 
	{\em tilde accent}, and {comment} modes.
\option{\bf--lang} 
	specifies the language {\em(english of french)} 
	for the textx like {\em Contents} or {\em Table es Matières}.
	The default (not surprinsingly) is {\em en} (english).
\option{\bf--lis} 
    writes out, as HTML comments, a list of the known definitions:
    \begin{itemize}
    \item	list of known \Atags
    \item	combined with the {\bf--tex} option, list the known 
	TeX {\em macros} and environments;
    \item	combined with the {\bf--html} option, list the
	{\em regular expressions}
        interpreted as HTML tags
    \end{itemize}
    Note that the macro {\tt\b list\{{\em titre}\}} generates also
    this list, when the {\bf--tex} option is specified.
    See also the {\bf--LIST}  option to produce the actual list of TeX macros.
\option{\bf--LIST} 
   issues a
   \A{/cgi-bin/cgiprint-plain?-LIST}{complete list of TeX macros}
    {\em with their equivalence},
   as a simple text.
\option{\bf--mail} | -+mail 
    asks to interpret {\em e-mail addresses};
    note that the form
    {\tt$<${\em adresse}[?Subject={\em sujet}]$>$} also recognized,
    as if written 
    {\tt $<$Mail:{\em e-mail\_adress}$>$}
    or {\tt $<$\%M {\em e-mail}$>$} (--glu)
    The {\bf -+mail} option disables this recognition.\\
    {\bf Note}:  email addresses are crypted.
\option{\bf--math\^{ }} 
    asks to intrepret the character {\tt\^{ }} (carret) as exponentiation,
    even outside the mathematical mode .
    The {\bf -+math} disables this interpretation.
\option{\bf--n {\em name}}
    assigns a name to the input stream -- its default name is
    {\tt(stdin)}. This option also changes the action of the
    macro {\tt\b thefile}.
\option{\bf--nomath}
    asks to use the standard font for the mathematical mode
    (what is between {\tt\$} ... {\tt\$}). The default is to
    {\em write the mathematical mode in italics}.
\option{\bf--nooutput}
    asks to {\em not edit the result} -- until the next
    {\bf\b enableoutput} macro.
\option{\bf--oglu}
    asks to ``filter'' the output by the program
    {\tt /usr/local/bin/glufilter}.
    This option also implies {\bf--glu}.
\option{\bf--o {\em programme}}
    asks to ``filter'' the output by the program
    {\em programme}. The options of {\em programme}, if any,
    are separated by an ampersand {\bf\&}.
    Typically, the {\bf--glu} option can be followed by 
    {\tt-o glu\&-D\&gluDic}.\\
    {\bf Note:} when the {\bf--sec} option is active, the
    program {\em must reside in the 
    directory {\bf \$HTTPD\_HOME/bin}}
    (the default value of \$HTTPD\_HOME  is {\tt/usr/httpd}).
\option{\bf--pre} 
    indicates that the text is already pre-formatted
    (blanks and newlines are meaningful).
    This option simply inserts the HTML {\em tags}
    {\tt $<$PRE$>$} at the beginning and {\tt $<$/PRE$>$} en fin
    (the {\bf -+pre}  option disables this interpretation).
\option{\bf--sec} {\em (secure)}
    restricts the access to files starting by the 8-character {\bf\magic}
    string \magic\ --
    any file not starting by this signature being rejected.
    In addition any executable program specified in the {\bf--o} option
    (see above) must be in the unique {\bf \$HTTPD\_HOME/bin} directory.
\option{\bf--tex} 
    indicates that the input text uses the TeX conventions.
    (the {\bf -+tex} option {\bf -+tex} disables this convention).
    See below the \secname{D\'efinitions TeX} section the details
    of the tex-like definitions.
\option{\bf--tex2} 
    indicates that the input text uses a `light-TeX'' format,
    as the one used for the abstracts: the symbols \{ \}, \%, \$
    keep their usual signification, indices are within underscores {\bf\_},
    the exponents are within carrets {\bf\^{ }}.
    Some other commonly used conventions are also recognized, like
    {\tt+{/}-} which is written $\pm$.
    The {\bf -+tex} option disables this convention.
\option{\bf--tag {\em tag\_prefix} }
    specifies the prefix used for the conversion of \Atags into actual
    anchors -- the default value of {\em tag\_prefix} is
    {\tt URL\_}
\option{\bf--v{\em version\_number}}
    defines the HTML version of the emulation used. 
    The default is {\bf 3.0}
\option{\em input\_file... }
    indicates the files to convert. The default is the 
    {\em standard input}.

\mansec{Tagge entities}
An \Atag, of general format
\fbox{{\tt $<$}{\em nom\_tag}{\bf:}{\em valeur}{\tt $>$}},
is by default onverted into
\fbox{{\tt$<$A href="\$\{URL\_}{\em nom\_tag}\}{\em valeur}"{\tt$>$}{\em valeur}{\tt$<$/A$>$}}
\\
i.e. the environment variable {\tt\$URL\_}{\em nom\_tag} is replaced,
and the argument follows.
For instance, the text
{\bf\tt $<$Essai:valeur$>$}
becomes:
{\bf\tt \<A href="\$\{URL\_Essai\}valeur"\>valeur\</A\>}

To be more detailed, if the variable {\tt\$URL\_Essai} is defined, either
in the standard Unix environment, or in the {\em tag\_file}, as\\
{\tt\$URL\_Essai=http://machine/cgi-bin/Programme? }\\
the the complete translation of {\tt \<Essai:valeur\>} is:\\
{\tt \<A href="http://machine/cgi-bin/Programme?valeur\>valeur\</A\>}

The {\em tagging prefix} {\tt URL\_} can be replaced by any other text
defined in the {\bf--tag} option, or by the environment variable {\tt TAG2HTML}.

\mansec{ tag\_file}
The first character of each line of a {\em tag\_file} means:
\begin{itemize}
\item[{\bf \#}] is a comment
\item[{\bf \$}] introduces  the definition of a variable (the {\bf=}  sign
	separates the variable name from its definition)
#	Exemple:
#	\begin{verbatim}
#	$URL_Fit=http://astro.u-strasbg.fr/cgi-bin/GetFits?
#	\end{verbatim}
#	permettra de convertir {\tt$<$Fit:II/202$>$} en
#	\begin{verbatim}
#	<A HREF="http://astro.u-strasbg.fr/cgi-bin/GetFits?II/202>II/202</A>
#	\end{verbatim}
\item[{\bf :}] introduces the definition of an \Atag. 
	Such a definition consists in 2 columns, {\em nom\_tag} and 
		{\em translation}.
	This {\em translation} may include:
	\begin{itemize}
	\item	references to definitions or environment variables,
		like {\tt\${\em nom}} ---
		for example {\tt\$\{URL\_Bib\}}
	\item	a reference to an {\em argument} --- {\tt\$0}
	\item	a reference to a {\em component} of an argument:
		{\tt\${$i$}} for the field number  $i$ of the argument
		assuming that the fields are separated by a {\em slash {\bf/}}.
		Another separator character is possible when following 
		directly the {\tt\$} ---
		e.g. \tt\$,2} represents the 2nd field of the second argument
		with the assumption that the {\em comma} is used as
		a separator.
	\item	a reference to {\em components untgil the end} of the argument:
		{\tt\$\${$i$}} asks for fields $i$, $i+1$, ...
		(default separator is the {\bf/});
		for example, {\tt\$\$,2} represents what follows the first
		comma of the second argument.
	\end{itemize}
	\par Example: the data concerning the cluster NGC 2244
	of the {\em Base de Donn\'ees sur les Amas}
	are tagged by 
	{\tt$<$Cat:BDA/ngc/2244$>$}. With the definition
	\begin{verbatim}
	:Cat:BDA/  http://vizier.u-strasbg.fr/cgi-bin/BDA?$$2
	\end{verbatim}
	the text {\tt$<$Cat:BDA/ngc/2244$>$} is converted into:
	\begin{verbatim}
	<A HREF="http://vizier.u-strasbg.fr/cgi-bin/BDA?ngc/2244">BDA/ngc/2244</A>
	\end{verbatim}
\item[{\bf\%}] definition of {\em GLU entities}.
	As above, the entity written 
	{\tt$<$\%E:BDA/ngc/2244$>$} is transformed into the anchor
	\begin{verbatim}
	<A HREF="http://vizier.u-strasbg.fr/cgi-bin/BDA?ngc/2244">BDA/ngc/2244</A>
	\end{verbatim}
	assuming the definition
	\begin{verbatim}
	%E:BDA/  http://vizier.u-strasbg.fr/cgi-bin/BDA?$$2
	\end{verbatim}
\item[{\bf $<$}] definition (in the form of a regular expression, 
	see {\bf grep}(1)) of the tags acceptable with the {\bf--html} option
\item[{\bf \b}] TeX definition.
	This definition is similar to a {\em TeX macro} definition.
	The number of arguments of the macro should be indicated with the
	{\bf\#} symbol followed by its number, followed by the
	definition within braces {\bf\{\dots\}}. For example, a 
	definition of the macro {\tt \b titre} can be done with: \\
	{\tt \b titre \quad	\#1\{\b$<$TITLE\b$>$\#1\b$<$/TITLE\b$>$\}} \\
	(beware to the separation between the name of the macro and the \#)
\item[{\bf \{}] definition of TeX environment. Parameters are possible,
	as e.g.:\\
	{\tt \{tabular\}    \#1TABLE}
\item[{\bf !}] {\tt \b cgidef} definitions (see next section)
\end{itemize}

\mansec{ {\tt\bf\b cgidef} definitions }
Any line starting by {\bf\magic}
indicates a context change -- permetting  a mixture of
documents written in TeX and in HTML.
The exact syntax is:

{\bf\magic} [begin$|$plain$|$html$|$tex$|$end] {\em[options]} \\
\dots\dots  {\em(definitions)} \\
{\bf\tt\}}

with the following meanings:
\begin{itemize}
\item[{\tt begin}]: démarre un nouveau contexte, sans définition particulière
	--- mais les definitions seront ``oubliées'' dès que
	{\tt\bf\b cgidef\{end\}} sera rencontré.
\item[{\tt plain}]: le texte est d\'ej\`a pr\'eformatt\'e, 
	pas d'interpr\'etation (tag {\tt$<$LISTING$>$})
\item[{\tt html}]: le texte est d\'ej\`a en HTML --- pas de conversions,
	on ne fait que g\'en\'erer ou rechercher les ``services'' 
\item[{\tt tex}]: le texte est en LaTeX, et ce texte est converti en
	HTML.
\item[{\tt end}]: on supprime toutes les d\'efinitions (TeX, ou services,
	{\em cf} la section tag\_file) du {\bf\magic}
	pr\'ec\'edent, ce qui peut par exemple
	remettre des d\'efinitions \`a leurs valeurs par d\'efaut.
	En effet, les d\'efinitions indiqu\'ees par {\bf\magic}
	sont empil\'ees, l'indication {\magic~end\}} supprime les
	effets du {\magic} pr\'ec\'edent. Un {\tt\b cgidef}
	sans magic {\em(ne contenant que des options)}
	n'est toutefois pas empilé.
\item[{\em[options]}] semblables \`a celles d\'ecrites dans la 
	section \secname{Options}, par exemple {\bf--mail} pour
	activer la reconnaissance automatique des adresses
	\'electroniques.
\end{itemize}

\mansec{D\'efinitions TeX}
La liste compl\`ete est g\'en\'er\'e par 
\A{/cgi-bin/cgiprint-plain?-LIST}{{\pgm} -LIST}.
Un tr\`es bref aper\c u des macros reconnues par d\'efaut:

\begin{itemize}

\item	contrôle de l'edition par les macros
	{\tt\b disableoutput} et 
	{\tt\b enableoutput} (voir également l'action de 
	l'option {\bf-nooutput})

\item	accents: les accents standards (grave comme {\tt\b\`{ }a}, 
	aigu, umlaut, tilde...),  ainsi que les \AA, sont connus

\item	fontes: les {\em tailles} ({\tt\b small}, {\tt\b Large}, 
	et autres {\tt\b footnotesize}), et les {\em formes}
	({\tt\b bf}, {\tt\b em}, et autres {\tt\b it}{\it aliques}).
	\`A noter: la macro {\tt\b fbox} g\'en\`ere un texte HTML
	\'ecrit en {\em rouge}... \\
	La macro {\tt\b fg\{}{\em couleur}{\tt\}} {\em(foreground)}
	ou bien {\tt\b color\{}{\em couleur}{\tt\}}
	choisit la couleur du texte.

\item	les {\tt\b chapter\{\dots\}} (traduits en {\tt <H1>}),
	{\tt\b section\{\dots\}}, etc

\item	les caract\`eres sp\'eciaux {\tt\b b} (backslash),
	{\tt\b\%}, {\tt\b\&}, {\tt\b\$}, etc...

\item	le d\'elimiteur de paragraphes {\tt\b par} 
	(ou une suite de lignes blanches), le retour \`a la ligne
	{\tt\b\b}

\item	en mode math\'ematique: l'alphabet grec (plus ou moins bien
	rendu...), et les symboles principaux {\tt\b pm} pour $\pm$,
	{\tt\b deg} pour le degr\'e, etc... Les indices et exposants,
	indiqu\'es en TeX par les symboles {\bf\tt\^{ }} 
	({\em carret} pour l'exposant) et {\bf\tt\_} ({\em underscore}
	pour l'indice)

\item	les environnements principaux: {\tt\{verbatim\}}, 
	{\tt \{itemize\}}, {\tt\{enumerate\}},
	mais \'egalement {\tt\{glossary\}} (d\'efinition de terme,
	chaque terme \'etant introduit par
	{\tt\b term\{{\em terme\_\`a\_d\'efinir}\}}.
	En fait, {\tt\b term} peut \^etre utilis\'e comme la variante
	de {\tt\b item} avec un param\`etre).

	{\bf Note 1}: le comportement par d\'efaut d'un environnement
	(dans le cas d'environnement non d\'efini dans la
	{\em tag\_file}, est de g\'en\'erer son correspondant HTML.
	Par exemple, {\tt\b begin\{FORM\}} est converti en
	{\tt<FORM>}, et {\tt\b end\{FORM\}} en {\tt</FORM>}.

	{\bf Note 2}: il est possible d'utiliser les macros 
	{\fg{red}\tt\bf\b Beg} et {\fg{red}\tt\bf\b End} au lieu de 
	{\tt\b begin} et {\tt\b end}, qui ont un param\`etre compl\'ementaire
	contenant les {\fg{red}\bf options HTML}. Ainsi \\
	{\tt\bf\b Beg\{tabular\}\{BGCOLOR="\b xcolor\{LightYellow2\}"\}\{rll\}}\\
	rajoute les options de couleur de fond dans une table HTML.

\item	en mode {\tt\{tabular\}}, la conversion est faite en HTML 3.
	Sont connues les macros \\
	{\tt\b multicolumn\{$n$\}\{{\em alignement 
	   [\b bg\{couleur\_background\}]}\}\{{\em texte}\}}
		(texte couvrant plusieurs colonnes), et\\
	{\tt\b Column\{{\em HTML options}\}\{{\em texte}\}}
	{\tt\b colheader\{{\em titre de colonne}\}}

\item	les macros {\tt\b label\{{\em texte}\}} (d\'efinition d'un label
	--- ou une {\em``named anchor''} dans le contexte HTML),
	et {\tt\b ref\{{\em texte}\}} (rappel d'une d\'efinition).

\item	les ancres sont d\'efinies par les macros :\\
	{\tt{\bf\b A}\{{\em URL}\}\{\atexte}\}, \\
	{\tt{\bf\b Arel}\{{\em URL\_relative}\}\{\atexte\}}, 
	(URL relative par rapport \`a l'endroit o\`u se trouve le
	document), ou bien \\
	{\tt{\bf\b Aref}\{{\em name}\}\{\atexte\}},
	{\em name} \'etant d\'efini par la macro {\tt\b label}.

\item	les {\bf\em windows} (ou {\em target}) qui ouvrent une fen\^etre
	sp\'ecifi\'ee en cliquant sur une ancre sont d\'efinies par:
	\begin{itemize}
\item	{\tt{\bf\b W}\{{\em window\_name}\}\{{\em URL}\}\{\atexte\}},
	et  \\
\item	{\tt{\bf\b Wrel}\{{\em window\_name}\}\{{\em URL\_relative}\}\{\atexte\}} \\
	(URL relative par rapport \`a l'endroit o\`u se trouve le
	document).\\
\item	{\tt\b Apop}\{{\em largeur}{\bf x}{\em hauteur}\}\{{\em URL}\}\{\atexte\}
	qui ins\`ere le r\'esultat dans une {\em pop-up}, par ex.
	{\tt\bf\b Apop\{640x480\}\{vizier_icon.gif\}\{ic\^one\}}
	\end{itemize}

\item	Les images peuvent être appelées par l'une des 3 macros:
	\begin{itemize}
	\item	{\tt{\bf\b image}\{{\em URL}\}} \quad pour une image simple
	\item	{\tt{\bf\b img}\{{\em URL}\}\{{\em texte}\}} \quad 
		pour une image, et un texte de remplacement (qui apparaît
		lorsque l'on place la souris sur l'image)
	\item	{\tt{\bf\b IMG}\{{\em URL}\}\{{\em texte}\}\{{\em HTLM 
			options}\}} \quad 
		identique à {\tt{\bf\b img}} à part son 3ème argument
		qui contient des options HTML comme {\tt border=0} ...
	\end{itemize}
	Voir également ci-dessous la macro {\tt{\bf\b imgoptions}}

\item 	la définition d'{\em\bf options} pour les tables, les images:
	\begin{itemize}
	\item	{\tt{\bf\b imgoptions}\{{\em HTLM options}\}} \quad
		met en place les préférences pour les éditions des images
		par exemple {\tt\bf\b imgoptions\{border=0 align=top vspace=4\}}
	\item	{\tt{\bf\b taboptions}\{{\em HTLM options}\}} \quad
		met en place les préférences pour les tableaux
		par exemple 
		{\tt\bf\b taboptions\{CELLPADDING=4 CELLSPACING=2 
		   \b bg\{honeydew\}\}}
	\item	{\tt{\bf\b rowoptions}\{{\em HTLM options}\}} \quad
		met en place les préférences pour les lignes des tableaux
		par exemple {\tt\bf\b rowoptions\{\b bg\{LightYellow\}\}}
	\item	{\tt{\bf\b thisrowoptions}\{{\em HTLM options}\}} \quad
		met en place les préférences pour {\em la prochaine
		ligne du tableau courant}.
		%{\em(attention, la mise en place ne concerne que la
		%{\bf\fg{DarkOrange}ligne suivante}!)}
	\end{itemize}

\item   les instructions de test.\\
    Quelques macros commen\c cant par {\bf\b if} permettent des tests;
    ils commencent par {\bf\fg{blue3}\b if...}, peuvent avoir une
    clause {\bf\fg{blue3}\b else} ou bien des clauses d'alternatives
    {\bf\fg{blue3}\b elsif...} (il n'y a pas de {\em then}),
    et se terminent par {\bf\fg{blue3}\b fi}. Il en existe quelques
    vari\'et\'es:
    \begin{itemize}
    \item {\bf\fg{blue3}\b ifmmode}: {\em true} si le texte courant est
    		en mode math\'ematique
    \item {\bf\fg{blue3}\b ifnum}: test num\'erique avec l'un des 3 op\'erateurs
    	  {\bf < = >}. Par exemple \\
	  {\tt\verb+\ifnum\thesection=2 section: 2\else ignore\fi+} \\
	  De m\^eme une alternative peut s'écrire {\bf\b elsifnum}.
    \item {\bf\fg{blue3}\b ifmatch\{{\em pattern}\}\{{\em text}\}}: 
    	    pattern-matching {\em \`a la Unix} utilisant les
	    caract\`eres {\bf * ? [ ] }. Par exemple: \\
	    {\tt\verb+\ifmatch{*.dat}\myfile Data file\fi+} \\
	    De m\^eme une alternative peut s'écrire {\bf\b elsifmatch}.
    \item {\bf\fg{blue3}\b ifregexp\{{\em regular\_expression}\}\{{\em text}\}}:
    	   utilisation  d'expressions r\'eguli\`eres {\em \`a la grep}.
	   Par exemple: \\
	   {\tt\verb+\ifregexp{arXiv:[0-9]\{4\}[.][0-9]\{4\}}{code}(preprint)\fi+} \\
	   De m\^eme une alternative peut s'écrire {\bf\b elsifregexp}.
    \item {\bf\fg{blue3}\b iftrue} et {\bf\fg{blue3}\b iffalse}.
    	  Ainsi commenter une partie de texte peut se faire simplement
	  par \quad {\bf\b iffalse} {\em comment} {\bf\b fi}
    \end{itemize}

\item	l'ex\'ecution de programmes ou scripts 
    {\bf\fg{DarkOrange}(arguments non rescann\'es)}:
    \begin{itemize}
    \item {\tt\b exec\{{\em commande}\}} \quad pour ex\'ecuter une
	commande et r\'ecup\'erer son texte g\'en\'er\'e 
    \item {\tt\b special\{! {\em commande}\}} \quad pour ex\'ecuter un
	programme, et imprimer son r\'esultat.
    \end{itemize}

    Pour illustrer la diff\'erence entre les 2 commandes;
    \begin{itemize}
    \item {\tt\verb+\exec{ls -l /etc/hosts}+} \\
	  \exec{ls -l /etc/hosts}
    \item {\tt \verb+\special{!ls -l /etc/hosts}+} \\
    	  \special{!ls -l /etc/hosts}
    \end{itemize}

    Il existe encore {\tt\b execexpanded} et {\tt\b specialexpanded}
    qui convertissent leur argument
    avant l'ex\'ecution -- voir la diff\'erence entre \\
    \begin{itemize}
    \item {\tt\verb+\execexpanded{ls -l \thefile}+} \\
	\execexpanded{ls -l \thefile}
    \item {\tt\verb+\exec{ls -l \thefile}+} \\
	\exec{ls -l \thefile}
    \end{itemize}

    {\bf Note}: {\tt\b execexpanded} est d\'efini par: 
    \begin{verbatim}
    \def\execexpanded#1{\expand1arg{#1}\exec{#1}}
    \end{verbatim}

\item	traitement d'expressions r\'eguli\`eres
    {\bf\fg{DarkOrange}(arguments non rescann\'es)}:
	{\tt\b sed\{{\em sed-command}\}\{text-on-which-to-apply-command\}}

	{\bf Note 1}: les arguments ne sont pas rescann\'es -- \`a moins
	d'utiliser {\tt\b expand1arg}, par exemple \\
	\begin{verbatim}
	\def\bleq#1{\expand1arg{#1}\sed{s/ /=/g}{#1}}
	\bleq{\exec{date}}
	\end{verbatim}
	\def\bleq#1{\expand1arg{#1}\sed{s/ /=/g}{#1}}
	\bleq{\exec{date}}

	{\bf Note 2}: comme dans sed(1), la commande {\bf y} pour
	faire l'équivalent d'un tr(1) est possible, par exemple
	\begin{verbatim}
	\sed{y/[A-Z][0-9]/[a-z]/}{TOUS4 LES3 CHIFFRES8 SUPPRIMES9...}
	\end{verbatim}
	donne: \\
	\sed{y/[A-Z][0-9]/[a-z]/}{TOUS4 LES3 CHIFFRES8 SUPPRIMéS9...}


\item	quelques macros utiles pour g\'en\'erer du HTML:
	\begin{itemize}
	\item {\tt\b tag\{{\em tag}\}} qui g\'en\`ere un {\em tag}
	 	HTML (mot(s) entre {\tt<\dots>})
	\item {\tt\b tagged\{{\em tag}\}\{{\em texte ``tagg\'e''}\}} ,
		met le {\em texte} entre 
		{\tt<{\em tag}>} et {\tt</{\em tag}>}
	\item {\tt\b begin\{html\}} et {\tt\b end\{html\}}
		indiquent une portion de texte qui est d\'ej\`a
		en HTML (pas de conversion)
	\end{itemize}

\item	quelques macros utiles dans le contexte de SIMBAD:
	\begin{itemize}
	\item {\tt\b object}\{{\em source\_name}\} qui 
		g\'en\`ere une ancre vers un object de Simbad.
	\item {\tt\b objS}\{{\em source\_name}\}\{texte\}
		permet d'avoir un {\em source\_name} différent
		du texte (en fait, la macro {\tt\b object}\{{\em source\_name}\}
		est équivalente à 
		{\tt\b objS}\{{\em source\_name}\}\{{\em source\_name}\})
	\item {\tt\b objnS}\{{\em source\_name}\}
		pour un object qui {\bf n'est pas dans Simbad}.
	\item {\tt\b objC}\{{\em nom_correct}\}\{nom\_erroné\}
		qui génère un lien vers Simbad à partir d'un nom {\em corrigé},
		en notifiant l'erreur.
	\item {\tt\b obja}\{{\em \@\_number}\}\{texte\}
		qui génère un lien vers Simbad à partir de son numéro interne
	\item {\tt\b objac}\{{\em \@\_number}\}\{texte\}\{coordonnées\}
		qui génère un lien vers Simbad à partir de son numéro interne,
		les coordonnées étant incluses (ce qui permet de faire des tris)
	\item {\tt\b objA}\{{\em \@\_number}\}\{texte\}
		qui génère un lien vers Simbad à partir de son numéro interne,
		pour un object sans position connue
	\end{itemize}

\item	quelques macros utles dans le contexte du GLU
	\begin{itemize}
	\item {\tt\b glutag}\{{\em action}\} qui 
		g\'en\`ere une {\em marque GLU} (action),
		c'est-\`a-dire traduite par {\tt\bf$<$\&}{\em action}{\tt\bf$>$}
	\item {\tt\b Aglutag}\{{\em action}\}\{texte\}
		qui en plus pr\'ecise le texte apparent;
		sa traduction est 
		{\tt\bf$<$\&}{\em action}{\tt\bf$|$}{\em texte}$>$
	\item {\tt\b gludata}\{{\em datatype}\}\{{\em valeur}\} qui 
		g\'en\`ere une {\em marque GLU\_data}, 
		c'est-\`a-dire traduite par 
		{\tt\bf$<$\%}{\em datatype} {\em valeur}{\tt\bf$>$}
	\item {\tt\b Agludata}\{{\em datatype}\}\{{\em valeur}\}\{\atexte\}
		qui  en plus pr\'ecise le texte apparent
	\item {\tt\b glupop}\{{\em nom{\bf\_}largeur}{\bf x}{\em hauteur}}\}\{{\em glutag}\}\{\atexte\}
		qui ins\`ere le r\'esultat dans une {\em pop-up}, par ex.
		{\tt\bf\b glupop\{640x480\}\{smb.query "HD 12"\}\{Etoile HD 12\}}
	\item {\tt\b CDShead}\{{\em titre}\}\{{\em logo\}} qui 
		g\'en\`ere les marques GLU propres au CDS
	\item {\tt\b CDSpage}\{{\em titre}\}\{{\em logo\}} qui 
		d\'emarre une page CDS (en plus de CDShead, rajoute
		le titre qui apparait en en-t\^ete du browser)
	\item {\tt\b CDStail}\{{\em sujet\_de\_mail}\} qui g\'en\`ere 
		la petite enveloppe pour messages \'eventuels
	\item {\tt\b CDStailmenu}\{{\em sujet\_de\_mail}\} qui en
		plus de {\tt\b CDStail} rajoute le menu standard CDS.
	\end{itemize}

\item	et pour finir, quelques macros particuli\'eres:
	\begin{itemize}
	\item {\tt\b cgidef\{{\em options}\}} permet de mettre en place des
		options ( cf section {\tt \b cgidef} ci-dessus)
	\item {\tt\b list\{}{\em texte introductif}{\tt\}} 
		qui liste toutes les d\'efinitions
		connues \`a l'endroit o\`u la macro appara\^\i t,
	\item {\tt\b ionZ\{}{\em numéro\_atomique\_ou\_symbole}{\tt\}}
		pour l'interprétation des numéros atomiques et/ou des 
		ions suivant les conventions astronomiques; par exemple
		{\bf\b ionZ\{\fg{DarkGreen}26.1\}} va donner
		{\bf\fg{DarkOrange}FeII}, tandis que 
		{\bf\b ionZ\{\fg{DarkGreen}CaI} donne
		{\bf\fg{DarkOrange}20.00}.
	\item {\tt\b quit} pour stopper \`a l'endroit 
		o\`u la macro appara\^\i t.
	\item {\tt\b thefile} qui contient le nom du fichier
	\item {\tt\b filedate} qui contient la date du fichier en argument,
		par exemple \verb+\filedate{\thefile}+
	\item {\tt\b theprogram} qui contient le nom du program (\pgm,
		ou bien {\tt\$SCRIPT\_NAME} dans un contexte httpd)
	\end{itemize}

\item	Un autre exemple, pour montrer comment on peut
	r\'ealiser des \A{/local/test.htx}{changements de couleur dans les
	backgrounds}
\end{itemize}

\mansec{Returned Status}
\pgm retourne 0 en cas de succ\`es, et 1 s'il y a eu un probl\`eme.

\mansec{Variables d'Environnement}

Quelques variables d'environnement peuvent \^etre utilisees:
\begin{itemize}
\item	{\bf \$HTTPD\_HOME} (lorsque le programme s'appelle
	{\tt Show-s}, c.a.d. l'option {\em secure} est activ\'ee:
	restriction de programmes dans {\tt\$HTTPD\_HOME/bin}, 
	cf option {\bf--o} ci-dessus.\\
	{\bf Par d\'efaut:} {\tt/usr/httpd}
\item	{\bf \$QUERY\_STRING} (lorsque le programme s'appelle
	{\tt Show} (\'eventuellement suivi de {\tt-s} ou {\tt-plain}):
	les arguments sont fournis dans cette variable d'environnement,
	suivant le protocole HTTP (cf httpd(1))\\
	{\bf Par d\'efaut:} arguments dans {\bf\b cgidef\{}
	(cf section {\bf\b cgidef\{})
\item	{\bf \$SCRIPT\_NAME} (lorsque le programme s'appelle
	{\tt Show} (\'eventuellement suivi de {\tt-s} ou {\tt-plain}):
	il sert \`a d\'efinir la macro {\tt\b theprogram}
\end{itemize}

\seealso{ glu(1) grep(1) httpd(1) latex(1) sed(1) tr(1)}

{\bf Note:} A function \\
{\bf char *cgitr({\em char *text, char *html\_version})} \\
is available in {\tt/usr/\$MACHINE/lib} which interprets the input
string {\em text} and returns a newly allocated interpreted result.

\mansec{Questions \& Probl\`emes}
\`a Fox (francois@simbad.u-strasbg.fr)
\end{manpage}
