\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
%----------

%%% 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\ est un filtre qui convertit un texte --- 
ensemble de fichiers {\em input\_file} 
ou {\em stdin} par d\'efaut --- en HTML, en g\'en\'erant des
{\em ancres} ou des {\em marques GLU} (dans l'option {\bf--glu})
\`a partir de certaines \Atags de forme g\'en\'erique
{\tt $<${\em nom\_tag}{\bf:}{\em valeur}$>$},
ou bien reconnues d'apr\`es le contexte.

Lorsque le nom de ce programme commence par {\bf Show},
il peut \^etre appel\'e pour des transformations directement
par le d\'emon {\bf httpd}(1); un exemple typique est la conversion
des Abstracts.

Un exemple d'\Atag est {\tt$<$Uni:{\em symbole\_d'unit\'e}$>$},
ou encore une {\em marque GLU} de type {\em entit\'e}
({\tt$<$\%{\em type} {\em valeur}$>$}) ou {\em action}
({\tt$<$\&{\em action} {\em valeur}$>$}).
Un {\em BibCode}, r\'ef\'erence bibliographique
form\'ee de 19 caract\`eres de forme {\tt YYYYJJJJJvvvvMppppA},
peut typiquement \^etre reconnu dans son contexte.

Le texte \`a convertir peut \^etre sous format {\em TeX} 
(avec l'option {\bf--tex}), sous un format {\em TeX-light} qui
contient seulement quelques bases de TeX et est utilis\'e pour
les {\em Abstracts} d'A\&A (avec l'option {\bf--tex2}),
ou d\'ej\`a en HTML (avec l'option {\bf--html}, ou entre
\b begin\{HTML\} et  \b end\{HTML\}).

\pgm\ permet \'egalement de {\em substituer les variables d'environnement},
soit par la macro TeX {\tt\b env\{...\}} (dans le contexte TeX),
soit par l'utilisation du {\tt\$} (dans le contexte html).
A noter que, tout comme dans le {\em shell}, les accolades
{\bf\{ \}} peuvent \^etre utilis\'ees pour ``coller'' des 
variables a un mot, par exemple {\tt\$\{var\}1}.

\mansec{ Usage }
Toutes les d\'efinitions --- sous quelle forme se trouve le texte
d'entr\'ee, quelles sont les {\em macros TeX} que peut contenir le texte,
comment convertir les \Atags en ancres HTML ou marques GLU, etc... ---
peuvent \^etre incluses dans un fichier appel\'e {\em tag\_file},
ou encore \^etre au d\'ebut du texte d'entr\'ee s'il commence
par {\bf\magic}

\mansec{Options}
\option{\bf--\%{\em lettre}}
    demande de {\em d\'esactiver} la reconnaissance automatique
    pour une ligne commen\c cant par {\tt\%-}{\em lettre}.
    Par exemple, {\bf\tt-\%R} permettra de ne pas g\'en\'erer d'ancre
    pour la ligne\\
    {\tt \%R 1996ApJS..123.1234A} \\
    lorsque la reconnaissance automatique des bibcodes est active.
\option{\bf--bib | -+bib} 
    demande de reconna\^\i tre automatiquement les {\em BibCodes}
    dans le texte d'entr\'ee, et de les transformer en ancres ou marques GLU
    (l'option {\bf -+bib} supprime cette reconnaissance).
    Un {\em bibCode}, pour \^etre reconnu, a besoin d'\^etre 
    sous sa forme canonique (19 caract\`eres) et s\'epar\'e des
    mots pr\'ec\'edent et suivant par un blanc, une virgule, 
    ou d'autres ponctuations non ambigues telles que parenth\`eses,
    crochets... 
    Ces bibcodes sont automatiquement interpr\'etes
    comme s'ils \'etaient \'ecrits sous la forme d'\Atags
    {\tt $<$Bib:{\em bibcode}$>$}
    ou {\tt $<$\%R {\em bibcode}$>$} (--glu)
\option{\bf--cat | -+cat} 
    demande de reconna\^\i tre les {\em CatCodes} --- codes
    d\'esignant des catalogues comme {\bf III/123},
    ou encore {\bf J/A+AS/112/234}
    (l'option {\bf -+cat} supprime cette reconnaissance).
    Ces entit\'es doivent toutefois
    \^etre entre ``parenth\`eses angulaires'' {\bf $<$\dots$>$},
    ou bien encore entre crochets {\bf[\dots]}.
    Ces {\em CatCodes} sont automatiquement interpr\'etes
    comme s'ils \'etaient \'ecrits sous la forme d'\Atags
    {\tt $<$Cat:{\em CatCode}$>$}
    ou {\tt $<$\%E {\em bibcode}$>$} (--glu)
\option{\bf--D{\em macro}={\em definition} }
    permet d'ajouter des d�finitions de macros sur la ligne de commande.
    La d�finition {\em doit \^etre accol�e � l'option --D},
    tout comme dans les d�finitions relatives au pr�-processeur du
    compilateur {\bf C}. A noter que le backslash {\tt\b} peut \^etre
    omis: par exemple
    {\tt -DmyURL=http://myhost} et {\tt -D'\b myURL=http://myhost'}
    sont equivalents.
\option{\bf--f {\em tag\_file} }
    repr\'esente un fichier qui contient les d\'efinitions.
    Voir ci-dessous la section \secname{tag\_file} pour les d\'etails.
    Les d\'efinitions par d\'efaut peuvent s'obtenir avec l'option {\bf--lis};
\option{\bf--HELP} 
    donne une liste des options, ainsi que la liste des macros TeX
    reconnues.
\option{\bf--html | -+html} 
    indique que le texte d'entr\'ee contient d\'ej\`a des ``tags'' HTML
    --- par exemple des formes comme {\tt$<$B$>$texte~gras$<$/B$>$}
    (l'option {\bf -+html} supprime cette reconnaissance).
    La liste des ``tags'' acceptables sont donn\'es dans la {\em tag\_file}
    (cf section \secname{tag\_file}), tandis que les ``tags'' non reconnus
    sont transform\'es litt\'eralement: ainsi le texte \\
    {\tt Recherche de quasars dans le domaine $2<z<3$} \\
    sera-t-il correctement traduit en \\
    {\tt Recherche de quasars dans le domaine 2\&lt;z\&lt;3}

    A noter: un ``tag'' HTML ne sera pas reconnu comme tel par d\'efaut
    (cf section \secname{tag\_file}) si:
    \begin{itemize}
    \item le {\tt$>$} ne se trouve pas sur la m\^eme ligne que le {\tt$<$}
    \item le premier mot (texte suivi d'un blanc) qui suit immediatement
	le {\tt$<$} n'est form\'e que de lettres toutes majuscules
	ou toutes minuscules. Ainsi,  \\
	{\tt$<$FONT {\em texte...}$>$} \\
	sera reconnu comme tag HTML, tandis que \\
	{\tt$<$Font {\em texte...}$>$} \\
	sera converti en {\tt\&lt;Font {\em texte...}\&gt;}
    \end{itemize}
\option{\bf--ic} 
	demande d'ignorer les commentaires; par d\'efaut,
	les commentaires sont transform\'es en commentaires HTML ---
	ce qui ne fait bien souvent qu'encombrer les r\'eseaux...
\option{\bf--keep[\^{ }\_\$\~{ }\%]}
	demande de consid\'erer les caract\`eres indiqu\'es comme
	{\em normaux}, c.\`a.d. qu'ils n'ont pas vocation \`a
	d\'emarrer le mode {\em exposant}, {\em indice}, {\em math\'ematique},
	{\em accent tilde}, ou encore {\em d\'ebut de commentaire}.
\option{\bf--lang} 
 	demande un langage {\em(anglais ou fran�ais uniquement)}
	pour les textes tel {\em Contents} ou {\em Table des Mati�res}
	Par d�faut -- comme toujours! -- le d�fault est {\em en}
	(anglais).
\option{\bf--lis} 
    g\'en\`ere, sous forme de commentaires HTML,
    une liste des d\'efinitions connues:
    \begin{itemize}
    \item	liste des \Atags reconnues
    \item	combin\'ee avec l'option {\bf--tex}, liste des {\em macros}
    	TeX et des environnement reconnus;
    \item	combin\'ee avec l'option {\bf--html}, liste des {\em expressions
        r\'eguli\`eres} reconnues comme \'etant du HTML
    \end{itemize}
    A noter que la macro {\tt\b list\{{\em titre}\}} g\'en\`ere
    \'egalement cette liste, lorsque l'option {\bf--tex}
    est active.
    Cf option {\bf--LIST} pour la liste actuelle des macros.
\option{\bf--LIST} 
   donne une 
   \A{/cgi-bin/cgiprint-plain?-LIST}{liste compl\`ete des macros TeX}
   %\A{/cgi-bin/cgiprint-plain?-o\&sort\&-LIST}{liste compl\`ete des macros TeX}
   connues par d\'efaut
    {\em avec leur \'equivalence},
   sous forme d'un simple texte.
\option{\bf--mail} | -+mail 
    demande de reconna\^\i tre les {\em adresses \'electroniques} 
    qui sont sous la forme {\tt$<${\em adresse}[?Subject={\em sujet}]$>$},
    comme si elles avaient \'et\'e \'ecrites
    {\tt $<$Mail:{\em e-mail\_adresse}$>$}
    ou {\tt $<$\%M {\em e-mail}$>$} (--glu)
    (l'option {\bf -+mail} supprime cette reconnaissance).\\
    {\bf Note}: les adresses �lectroniques sont crytp�es; et le sujet
    du mail n'est pas �dit� dans le texte HTML.
\option{\bf--math\^{ }} 
    demande d'interpr\'eter les {\tt\^{ }} (carret) comme des
    exponentiations, m\^eme en-dehors du mode math\'ematique
    (l'option {\bf -+math} supprime cette interpr�tation).
\option{\bf--n {\em name}}
    est utile pour donner un nom au stream d'entr\'ee dont le nom
    par d\'efaut est {\tt(stdin)}. Cette option affecte le contenu
    de la macro {\tt\b thefile}.
\option{\bf--nomath}
    demande d'utiliser le fonte standard pour le mode math\'ematique
    (ce qui est entre {\tt\$} ... {\tt\$}). Par d\'efaut, le
    {\em mode math\'ematique est \'ecrit en italiques}.
\option{\bf--nooutput}
    demande de ne {\em pas �diter le r�sultat} -- jusqu'� la
    macro {\bf\b enableoutput}.
\option{\bf--oglu}
    demande de ``filtrer'' le texte g\'en\'er\'e par le programme
    {\tt /usr/local/bin/glufilter}.
    Cette option implique \'egalement {\bf--glu}.
\option{\bf--o {\em programme}}
    demande de ``filtrer'' le texte g\'en\'er\'e par le programme
    {\em programme}. Les options \'eventuelles de {\em programme}
    sont s\'epar\'ees par des esperlu\`etes {\bf\&}.
    Typiquement, l'option {\bf--glu} pourra \^etre suivie de
    {\tt-o glu\&-D\&gluDic}.\\
    {\bf Note:} lorsque l'option {\bf--sec} est active, le
    programme {\em doit imp\'erativement se trouver dans le
    directory {\bf \$HTTPD\_HOME/bin}}
    (\$HTTPD\_HOME vaut {\tt/usr/httpd} par d\'efaut).
\option{\bf--pre} 
    indique que le texte est d\'ej\`a {\em pr\'e-formatt\'e}
    (les blancs et fins de lignes sont significatifs).
    Cette option encadre simplement le texte par les {\em tags} HTML
    {\tt $<$PRE$>$} en d\'ebut et {\tt $<$/PRE$>$} en fin
    (l'option {\bf -+pre} supprime cette interpr�tation).
\option{\bf--sec} {\em (secure)}
    restreint l'acc\`es aux fichiers commen\c cant par la
    signature (``magic'') des 8 caract\`eres {\bf\magic}.
    Tout fichier ayant une autre signature sera rejet\'e.
    De plus, les programmes ex\'ecutables dans l'option {\bf--o}
    (cf ci-dessus) se trouvent obligatoirement dans un directory
    unique {\bf \$HTTPD\_HOME/bin}.
\option{\bf--tex} 
    indique que le texte est sous une forme TeX relativement
    \'elabor\'ee --- les accents, quelques d\'efinitions et environnement
    de base --- dont les tables --- sont connus et peuvent \^etre d\'efinis
    (l'option {\bf -+tex} supprime cette reconnaissance).
    Voir ci-dessous dans la section \secname{D\'efinitions TeX} les 
    d\'efinitions connues par d\'efaut.
\option{\bf--tex2} 
    indique que le texte est sous une forme ``light-TeX''
    utilis\'ee pour les Abstracts: les crochets \{ \}, \%, \$
    gardent leur signification habituelle, les indices sont encadr\'es
    par des {\bf\_} (underscore), les exposants par des {\bf\^{ }}
    (carrets). Quelques autres \'ecritures sont \'egalement reconnues
    comme {\tt+{/}-} qui devient $\pm$.
    L'option {\bf -+tex} supprime cette reconnaissance.
\option{\bf--tag {\em tag\_prefix} }
    pr\'ecise le pr\'efixe utilis\'e pour la conversion des \Atags
    en ancres --- la valeur par d\'efaut de {\em tag\_prefix}
    est {\tt URL\_}
\option{\bf--v{\em version\_number}} (symbols accol\'es) 
    pr\'ecise la version HTML. Par d\'efaut, {\bf 3.0}
    qui conna\^\i t les tables.
\option{\em input\_file... }
    indique les fichiers \`a convertir. Par d\'efaut, le
    {\em standard input} est utilis\'e comme fichier d'entr\'ee.

\mansec{Entit\'es tagg\'ees}
Une \Atag, de forme g\'en\'erale
\fbox{{\tt $<$}{\em nom\_tag}{\bf:}{\em valeur}{\tt $>$}},
est convertie par d\'efaut en:
\fbox{{\tt$<$A href="\$\{URL\_}{\em nom\_tag}\}{\em valeur}"{\tt$>$}{\em valeur}{\tt$<$/A$>$}}
\\
c'est-\`a-dire qu'on fait appel \`a la variable d'environnement
{\tt\$URL\_}{\em nom\_tag} \`a laquelle on accole l'argument.
Par exemple, le texte
{\bf\tt $<$Essai:valeur$>$}
devient:
{\bf\tt \<A href="\$\{URL\_Essai\}valeur"\>valeur\</A\>}

Si par ailleurs la variable {\tt\$URL\_Essai} est d\'efinie, soit
dans l'environnement standard Unix, soit dans la {\em tag\_file}, par\\
{\tt\$URL\_Essai=http://machine/cgi-bin/Programme? }\\
alors la traduction compl\`ete de {\tt \<Essai:valeur\>} est:\\
{\tt \<A href="http://machine/cgi-bin/Programme?valeur\>valeur\</A\>}

Le {\em pr\'efixe de taggage} {\tt URL\_} peut \^etre replac\'e par tout autre
texte d\'efini par l'option {\bf--tag}, ou encore par la variable
d'environnement {\tt TAG2HTML}.

\mansec{ tag\_file}
Le premier caract\`ere de chaque ligne de la {\em tag\_file} indique
le type de d\'efinition :
\begin{itemize}
\item[{\bf \#}] ligne de commentaire. 
\item[{\bf \$}] d\'efinition de variable. 
	Le signe {\bf=} soit s\'eparer le nom de la variable de sa d\'efinition.
#	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 :}] d\'efinition d'\Atag. Une telle d\'efinition est
	faite de 2 colonnes, {\em nom\_tag} et {\em traduction}.
	Cette {\em traduction} peut contenir
	\begin{itemize}
	\item	des r\'ef\'erences \`a des d\'efinitions ou des variables
		d'environnment, sous la forme {\tt\${\em nom}} ---
		par exemple {\tt\$\{URL\_Bib\}}
	\item	une r\'ef\'erence \`a l'{\em argument} --- {\tt\$0}
	\item	une r\'ef\'erence \`a une {\em composante} de l'argument:
		{\tt\${$i$}} pour le $i$-\`eme champ de l'argument,
		les champs \'etant s\'epar\'es par un {\em slash {\bf/}}.
		Un autre caract\`ere s\'eparateur est possible en
		le mettant directement apr\`es le {\tt\$} ---
		par exemple {\tt\$,2} repr\'esente le 2\`eme champ de
		l'argument en supposant la {\em virgule} comme 
		caract\`ere s\'eparateur
	\item	une r\'ef\'erence \`a {\em toutes les composantes
		jusqu'\`a la fin} de l'argument:
		{\tt\$\${$i$}} pour les champs \`a partir du $i$-\`eme 
		(s\'eparateur par d\'efaut: {\bf/});
		{\tt\$\$,2} repr\'esente ce qui suit la premi\`ere
		virgule rencontr\'es dans l'argument.
	\end{itemize}
	\par Example: les donn\'ees concernant l'amas NGC 2244
	de la {\em Base de Donn\'ees sur les Amas}
	sont tag\'ees dans le texte par 
	{\tt$<$Cat:BDA/ngc/2244$>$}. Moyennant la d\'efinition
	\begin{verbatim}
	:Cat:BDA/  http://vizier.u-strasbg.fr/cgi-bin/BDA?$$2
	\end{verbatim}
	le texte {\tt$<$Cat:BDA/ngc/2244$>$} sera converti en:
	\begin{verbatim}
	<A HREF="http://vizier.u-strasbg.fr/cgi-bin/BDA?ngc/2244">BDA/ngc/2244</A>
	\end{verbatim}
\item[{\bf\%}] d\'efinition d'{\em entit\'e GLU}. Comme ci-dessus,
	l'entit\'e \'ecrite dans le texte
	{\tt$<$\%E:BDA/ngc/2244$>$} sera transform\'e\'e en ancre
	\begin{verbatim}
	<A HREF="http://vizier.u-strasbg.fr/cgi-bin/BDA?ngc/2244">BDA/ngc/2244</A>
	\end{verbatim}
	moyennant la d\'efinition
	\begin{verbatim}
	%E:BDA/  http://vizier.u-strasbg.fr/cgi-bin/BDA?$$2
	\end{verbatim}
\item[{\bf $<$}] d\'efinition (sous forme d'expression r\'eguli\`ere,
	cf {\bf grep}(1)) de tags valides avec l'option {\bf--html}
\item[{\bf \b}] d\'efinition TeX, avec sa correspondance HTML.
	Cette d\'efinition est similaire \`a celle d'une
	{\em macro TeX}; si des param\`etres sont souhait\'es,
	le {\em nombre de param\`etres} est \`a indiquer \`a
	l'aide du symbole {\bf\#} suivi du nombre de param\`etres, puis
	la d\'efinition entre {\bf\{\dots\}}. Par exemple, la
	d\'efinition de la macro {\tt \b titre} se fait par: \\
	{\tt \b titre \quad	\#1\{\b$<$TITLE\b$>$\#1\b$<$/TITLE\b$>$\}} \\
	(attention \`a la s\'eparation entre le nom de la macro et
	le \#)
\item[{\bf \{}] environnement TeX, avec sa correspondance HTML.
	Des param\`etres sont \'eventuellement possibles, par exemple:\\
	{\tt \{tabular\}    \#1TABLE}
\item[{\bf !}] definitions du {\tt \b cgidef} (cf section ci-dessous)
\end{itemize}

\mansec{ {\tt\bf\b cgidef} d\'efinitions }
Toute ligne qui commence par {\bf\magic}
permet de changer le contexte, autorisant ainsi le m\'elange
de documents par exemple \'ecrits en TeX et en HTML.
La syntaxe est la suivante:

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

avec les significations suivantes:
\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 utiles 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 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 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 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}
