source: git/doc/STYLEGUIDE @ f0aa86

* texinfo *
===========

+ nach einer @table muss eine Leerzeile kommen, sonst steht im info-File
  die nachfolgende Zeile in der letzten Tabellenzeile mit drin.

+ Das Argument von @cindex, @chapter, @section und @subsection darf
  nicht in geschweiften Klammern stehen, auch wenn es Leerzeichen
  enthaelt. (Das Argument geht bis zum Ende der Zeile.)
    @cindex Procedures
    @section Getting started

+ Taucht ein Punkt innerhalb eines Satzes auf (z.B. als Ende einer
  Abkuerzung), so sollte darauf ein @: folgen. Sonst erscheint im
  Ausdruch ein zu grosser Abstand zum nachfolgenden Wort:
    compute w.r.t.@: a wellordering
    a Groebner resp.@: standard basis

+ Fuer Aestheten: anstatt der Quotes "..." die TeX Quotes verwenden
  ``...''.

+ Die Zeichen @ und { und } muessen in texinfo mit @ "gequoted"
  werden (nicht mit Backslash!).
  Der Backslash muss nicht gequoted werden:
    @  muss als  @@  geschrieben werden
    {  muss als  @{  geschrieben werden
    }  muss als  @}  geschrieben werden
    \  wird als  \   geschrieben
  ACHTUNG: Dies gilt natuerlich nicht in Beispielen, die von doc2tex
  gelesen und in Singular verarbeitet werden! Dort duerfen die Zeichen
  nicht gequoted werden, das macht doc2tex alleine. Dies gilt insbesondere
  auch fuer Dateien, die ueber @c include eingelesen werden.

+ Bei Aenderung von @node-Namen daran denken, dass der entsprechende Name
  auch im vorherigen und naechsten @node geaendert werden muss.
  Bei Aenderung von (Sub)sections daran denken, die Menues auf den neuen
  Stand zu bringen.
  Fehlerhafte @node- und @menu-Strukturen sieht man, wenn man singular.hlp
  erzeugt.

+ bislang wurde von texinfo nach einem @tex Kommando zu viel space
  eingesetzt. Der Fehler ist im texinfo behoben. Man kann nun also auch
  mitten in einem Satz auf @tex umschalten, ohne etwas wie \noindent
  einsetzen zu muessen.

+ fuer Ellipsen (...) das Kommando @dots{} verwenden.  Eine Ellipse am Ende
  eines Satzes mit @enddots{} schreiben.

+ Email Adressen in @email{...} notieren, URL's in @url{...}

+ Multicolumn tables: Rows of multicolumn tables need to go in one
  line, otherwise texi2html chockes. Space beween rows with "empty"
  rows (c.f. texi2html), i.e., with @item @tab @tab ....


* tex *
=======
+ Use @math{...} as you would use $..$ in latex -- i.e., ANY
  mathematical symbols should be within @math (or, @tex, if they
  require special tex symbols)

+ don't use \mbox, use \hbox, instead

+ use \hbox only within math environment

+ don't use any sophisticated tex commands (like \eqalign), restrict
  yourself to command which latex understands, as well.

+ no "@"-constructs within @tex ... @end tex

+ @tex and '@end tex' should always be on separate lines

+ keine latex-Konstrukte in @tex.. @end tex, 
  also z.B. kein \begin{..}...\end{..}, etc.:
  hier darf nur auftauchen, was sowohl von tex als auch von latex
  verstanden wird

* Notationen *
==============

+ Schreibweise von Singular:
    im Text: @sc{Singular}
    in Singular-Kommentaren von Singular-Beispielen: SINGULAR
    in Ueberschriften: SINGULAR

+ Alle Singular-Befehle und -Variablen werden im Style @code
  geschrieben:
    @code{std}, @code{TRACE}

+ Singular-Typen werden NICHT im Style @code geschrieben:
    int, intmat

+ Tasten, die man druecken muss, werden im Style @code geschrieben.
  Die Control-Taste wird als CTRL abgekuerzt:
    @code{CTRL-A}
  Fuer RETURN, SPACE, etc, sollte @key{RETURN} verwendet werden.
  (die html-UMsetzung hat Schwierigkeiten mit <SPACE> etc.)

+ Gross/Kleinschreibung von Ueberschriften: Das erste Wort wird gross
  geschrieben, alle anderen klein. Ausnahme: Wenn das erste Wort ein
  reserviertes Wort von Singular ist, wird es so geschrieben, wie man
  es in Singular schreibt:
    Functions and system variables
    int related functions
    TRACE

+ Die Funktionsweise von Funktionen (vor allem im Kapitel "Functions", aber
  auch z.B. Kommandozeilen-Optionen, etc.)  wird in der dritten Person
  beschrieben. Sie fangen mit einem Kleinbuchstaben an und schliessen mit
  einem Punkt.  Bitte vollstaendige Saetze formulieren.

    npars: returns the number of ring parameters.

  Statt "will be" wird "is" verwendet:

    the result is a standard basis (statt will be a standard basis)

+ Fuer Kardinalzahlen: 0th, 1st, 2nd, i-th n-th



* Schreibweisen *
=================

+ "standard basis" statt "standardbasis"

+ "basering" statt "base ring"

+ "Groebner" (ohne Umlaut)

+ "I/O" statt "i/o"

+ Meistens verwenden wir den Begriff "monomial ordering".

+ "Computer Algebra" statt "computer algebra"

+ Konstrukte wie "the ideal/module is..." vermeiden. Stattdessen etwa
  "the ideal, resp.@: module, is..." schreiben.

+ non-zero, zero-dimensional, zero-set: use hyphen; Plural of zero:
  zeros (instead of zeroes)

+ Zum Englischen: "i.e.", "e.g.", "for example", "that is",
  "resp. ..."  usw. werden immer in Kommas eingebettet:
    @sc{Singular}, for example, has the ...
  Nach einem Doppelpunkt schreiben wir klein weiter:
    Purpose: computes the dimension.

+ Die pers"onliche Anrede des Lesers vermeiden.  Insbesondere die Worte
  `you', `your', etc. vermeiden.

* Singular Beispiele und libraries *
====================================

* generally, use @samllexample for (code) examples

+ Ist der Kommentar zu einem Kommando in einem Beispiel, das von Singular
  gerechnet werden soll, laenger als eine Zeile, muss das Kommando in der
  untersten Zeile des Kommentars stehen (sonst wird in spaeter die
  Singular-Ausgabe zwischen den Kommentar und das Kommando geschoben):
@smallexample
@c example
  ring r;
                 // the following option leads to some useful output
  option(prot);  // during the Groebner basis computation.
@c example
@end smallexample

+ Bei Beispielen, die nicht wirklich von doc2tex gerechnet, muss nach dem
  @expansion ein Leerzeichen kommen, und geschweifte Klammern muessen
  gequoted werden mit @:
@smallexample
int i=3;
    // Kommentare ueber mehere Zeilen duerfen natuerlich
i;  // mit Leerzeichen beginnen.
@{@} // quote von geschweiften Klammern
@expansion{} 3
@end smallexample

+ Beim Schreiben von Singular-Beispielen (insbesondere von
  Kommentaren) bitte darauf achten, dass die Zeilen nicht zu breit
  werden. (Sonst bekommt man "overfull hbox"-Meldungen um die Ohren
  geschmissen.)

+ Hilfe-Texte in Libraries: keine TAB's verwenden

* Cross-Referenzen *
====================

+ es gibt drei Type von Cross-Referenzen (erste Zeile - Beispiel,
  zweite Zeile - Resultat in Info, dritte Zeile - Resultat in TeX):


  @xref      fuer den Anfang eines Satzes

             @xref{Tropical Storms}, for more info.
             *Note Tropical Storms::, for more info.
             See Section 3.1 [Tropical Storms], page 24, for more info.

  @ref       fuer den Ende eines Satzes

             For more information, see @ref{Hurricanes}.
             For more information, see *Note Hurricanes::.
             For more information, see Section 8.2 [Hurricanes], page 123.

  @pxref     fuer geklammerte Referenzen

             ... storms cause flooding (@pxref{Hurricanes}) ...
             ... storms cause flooding (*Note Hurricanes::) ...
             ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...

+ @xref und @ref *muessen* immer von einem Komma oder einem Punkt
  oder einem Semikolon abgeschlossen werden.  Wie oben aufgefuehrt, sollte
  @xref immer am Satzanfang stehen, @ref dagegen immer am Satzende.
  Ausnahmen sind Listen von @ref's, wie unten beschrieben.

+ @pxref darf nur innerhalb einer Klammer auftauchen.  Und zwar nur ein
  einzelnes, keine Liste von @pxref's.

+ mit der neuen Version von doc2tex kann (soll) man Listen von
  Cross-Referenzen wie folgt schreiben:
    @c ref
    See
    @ref{std};
    @ref{stdfac};
    @ref{stdhilbert}.
    @c ref
  Daraus wird dann automatisch ein Menue fuer die info-Files erzeugt.
  (Man kann sich also das "@menu * std:: ...  @end menu" sparen.)
  Bitte pro Zeile nur *eine* Referenz notieren und das `See'
  in eine eigene Zeile packen.  Das macht die Sache
  uebersichtlicher.  Ausserdem kann man die Referenzen dann
  leichter im Editor handhaben (loeschen, alphabetisch
  sortieren).
  Die Referenzen bitte alphabetisch sortieren und mit einem Semikolon
  trennen.

* Index, Anchors*
==================
+ Do not hesitate to insert many index entries. Each index entries
  needs to be written on one line. For one topic, insert different
  formulation of the index entries. For example:
@cindex The online help system
@cindex online help
@cindex help, online help system
  Generally, if an index topic needs to be specified further, mention
  the general topic first, separated by comma, and followed by
  specialization (like "help, online help system").

+ Use the @anchor{label} construct, to set arbitraty labels, to which
  you can refer to with @ref{label}. For example:
@anchor{option(prot);}
  Put the @anchor before the explained topic, otherwise the html
  display might cut the first line(s) of the explained topic.



* Umlaute *
===========
@"o                 "o      umlaut accent
@'o                 'o      acute accent
@,{c}               c,      cedilla accent
@=o                 =o      macron/overbar accent
@^o                 ^o      circumflex accent
@`o                 `o      grave accent
@~o                 ~o      tilde accent
@dotaccent{o}       .o      overdot accent
@H{o}               ''o     long Hungarian umlaut
@ringaccent{o}      *o      ring accent
@tieaccent{oo}      [oo     tie-after accent
@u{o}               (o      breve accent
@ubaraccent{o}      o_      underbar accent
@udotaccent{o}      o-.     underdot accent
@v{o}               <o      hacek or check accent
@ss{}               ss      es-zet or sharp S

* allgemeines *
===============

+ Die Funktionalitaet von doc2tex ist im sourcecode ausfuehrlich
  domkumentiert. Siehe doc2tex.pl - Vorspann.
+ Innerhalb einer @tex-Umgebeung keine texinfo-Befehle (wie @ref) verwenden.

+ neuere latex2html-Versionen erfordern das Aendern von
  /usr/lib/latex2html/l2hconf.pm
  $DVIPSOPT = ' -Ppdf -E -r0'; -> $DVIPSOPT = ' -E -r0';
  da sonst die PDF-Fonts benutzt werden, die fuer schware Unterstriche in den
  Formal sorgen.
------------------------------------------------------------
$Id$