Re: [gpdoc] A uniform style.

[Layla Raid <kb@libertysurf.fr>]

On Fri, 5 Jul 2002, Olivier Ramare wrote:
>   About syntax in this dear usersch3.tex ....
> I've tried to understand how entries are written
> and how they should be written. To get a documented
> standard way for --yes !!-- external contributors !

The most horrible hacks are (tersely) documented in parimacro.tex.
I have appended a slightly more readable account.

> What exists :
>
> -- \subsecidx{max} indicates a function.
>        -- name written,
>        -- entry in the index,
>        -- section number here.
> -- \idx{or} indicates a function.
>        -- name written,
>        -- entry in the index.

There are 3 kinds of index entries: standard, GP concept, keyword

\idx is for the generic kind of entries.
\tev and \tet correspond to the 2 other kinds.

> -- \sidx{or} is to put only an entry in the index under
>    this name but not print the argument ("or" here).

yes, "s" is for "silent"

> -- \kbdsidx{} ?? not used ? no use ?

put entry in index (keyword), don't print argument

> -- \syn{gmax} indicates a library counterpart.
> -- \synt{direuler} is what ??

\syn only hints at the actual function prototype (using the general convention
that args are GEN, prec is long, etc)

\synt gives the full function prototype, arguments are typeset in "verbatim" mode.

> -- \kbd(numtoperm) indicates a function when used inside
>    the text. But what about \kbd{long} and \kbd{GEN} ??
>    change them to something else ? "\type(long)" ?
>    What about \kbd{issquare}$(x,\{\&e\})$
>           and \kbd{lex([1,3], [1,3,-1])} ?

\kbd{} indicates a keyword, or more generally something that would be input
exactly as written (\kbd is short for "keyboard input").

I.e you would type \kbd{issquare(4, \&e)}, but \kbd{issquare}$(x,\{\&e\})$ since
in actual text the {} would be omitted, also x is just a general argument
placeholder.

You can distinguish betwen various kinds of keywords and introduce \type{} if you
think it's clearer. Also possibly \verb{} for verbatim input.

> -- $\teb{gmin}(x,y)$ ?? a function that should be classed
>    in the same place ...
>    A function which appears for the first time
>    and is thus refered here but with no independant section ?

Not idea about the acronym [ b = "bold", te = table (index) entry ? ]

A C function "definition" [ mostly referenced in the "The library syntax is"
section ]. Typeset in bold, and referenced as keyword in the index.

It is not used very consistently (e.g \teb{qfbclassno}, when no such C function
exists)

> -- \tet{permtonum} is ??

Keyword refered to in the index. Short for \kbd{} + \idx{}

> -- \teb{ggprecision} is what ??

see above

> -- $\tev{nf}$ is the usual name of a variable.

No. Pari/GP concept (indexed, typeset as \var{})

> -- examples of session are currently between \bprog and @eprog.

That's my worst hack: \bprog sets up partial verbatim mode until the <eprog> token.
Partial in the sense that @ becomes the control character instead of \.
If the <com> (= comment) token is met in verbatim mode, its argument is parsed
normally (non-verbatim!).

The point was to use standard TeX for comments in the middle of verbatim code.
Looks nice, but probably not a good idea [TeXmacs can't parse Pari documentation
for instance]


You also have \bprogpart which leaves $ and _ alone (are parsed by TeX as usual)
[ used only once I think ]

>   So if anyone has a better understanding of the existing structure
> of this chapter 3 ... and even could answer to the above questions ?

I wrote the above macros as they currently stand.

Since gphelp is the only external tool which needs to parse directly the manual,
you can certainly design a more consistent naming scheme / macro system, esp. if
you propose to document it ! Simply remember that gphelp needs to be updated at
the same time [ I can do this ].

Also the TeX setup was chosen in the early eighties, it could be interesting to
converge to a more modern documentation system. But a transition should be no real
problem provided the docs are properly structured [ there was a message sent to
the list about converting the docs to texinfo, there's a reference to the package
on my gp page ]

Hope this helps,

  Karim.

P.S1: Thanks for taking this up :-)

P.S2: Here's the full list of macros from (current CVS) parimacro.tex [just
deleted \f, \d, \p]

\vers: version number
\miscdir: miscdir from Configure
\includedir: includedir from Configure
\libdir: libdir from Configure
\wwwsite: WWW site address (currently http://www.parigp-home.de/)

% crossref
\label / \ref: as in LaTeX   (pdflatex-friendly)
\secref#1: Section~\ref{#1}

% index
\idx: typeset as \rm, indexed
\teb: typeset as \key, indexed as "keyword"
\tet: typeset as \kbd, indexed as "keyword"
\tev: typeset as \var, indexed as "Pari/GP concept"
\sidx{}: as \idx, but not typeset
\kbdsidx{}: as \tet, but not typeset

% C function prototypes
\fun{ret}{f}{arg}: C function 'f' with return type 'ret', arguments 'arg' [ f goes
to index ]. f and arg are parsed in verbatim mode (e.g _ not a problem)
\funno: as above, no index
\funs{f}{arg}: "simple" \fun (no return type)

% sections:
\chapter#1 (+ \appendix, \section, \subsec, \subsubsec)

\subseckbd: \subsec + \kbd (used for operators)
\subsecidx: \subsec + \tet
\subsubsecidx: \subsubsec + \tet

\misctitle#1: miscellaneous title (eg: "Warning:"), doesn't appear in TOC.
\newpage: start a new page

\unix: current paragraph discusses Unix-specific feature
\emacs: current paragraph discusses Emacs-specific feature

\sectionunix
\subsecunix
\subsubsecunix
\subsecidxunix
\subsubsecidxunix: as \section et al., Unix specific

% miscellaneous
\goth{x}: x typeset in gothic (eufm10)
\key{x}: x typeset as {\bf #1}  [ legacy, should be removed / renamed / used in a
                                  consistent way ]

\kbd{x}: x typeset as verbatim text (currently \tt)
\var{x}: x typeset as a "variable" (currently \it)
\fl: 'flag' typeset as a "variable" (without ugly ligature 'fl')
\B: \kbd{BIL}  (for "Bits In Long")
\op: \var{op}  (for "operator")

\text: typeset as text [ much weaker than amsmath's version ]
\Z: integers
\Q: rational numbers
\F: finite field
\R: real numbers
\C: complex numbers   [ all typeset as {\bf...}. Should be fixed as \mathbb ]

\bs: \ (backslash)
\obr: { (opening brace)
\cbr: } (closing brace)
\pow: ^ (for use in \kbd mode)
\til: ~ (for use in \kbd mode)
\b{a}: \a in \kbd mode
\mod: \text{mod}, with (minimal) spacing

\dfrac{a}{b}: a/b is display math
\binom{n}{p}: binomial coeff
\typ{REAL}: t_REAL in \kbd mode, with verbatim _

--
Karim Belabas                    Tel: (+33) (0)1 69 15 57 48
Dép. de Mathematiques, Bat. 425  Fax: (+33) (0)1 69 15 60 19
Université Paris-Sud             Email: Karim.Belabas@math.u-psud.fr
F-91405 Orsay (France)           http://www.math.u-psud.fr/~belabas/
--
PARI/GP Home Page: http://www.parigp-home.de/