source: git/doc/STYLEGUIDE @ e331a7a

* 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{...}

* 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}

+ 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")
  wird in der dritten Person beschrieben. Statt "will be" wird "is"
  verwendet:
    vdim: returns the vector space dimension ....
    the result is a standard basis (statt will be a standard basis)

* 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.

+ Zum Englischen (Dank an Olaf und Christian):
  "i.e.", "e.g.", "for example", "that is" 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 *
====================================

+ Die Kommandozeilen in einem Beispiel beginnen mit zwei Leerzeichen:
@example
  ring r;
  ideal i=x,y;
@end example

+ 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):
  @example
  @c example
    ring r;
                   // the following option leads to some usefule output     
    option(prot);  // during the Groebner basis computation.
  @c example
  @end example

+ Bei Beispielen, die nicht wirklich von doc2tex gerechnet, muss nach dem
  @expansion ein Leerzeichen kommen:
  @example
    int i=3; i;
    @expansion{} 3
  @end example

+ 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.)

+ Kommando-Beschreibungen (Purpose:) fangen mit einem Kleinbuchstaben an,
  sind in der dritten Person Singular gehalten und schliessen mit einem
  Punkt.  Vollstaendige Saetze formulieren.  Beispiel:

  Purpose:  returns the number of ring parameters.

+ 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.

------------------------------------------------------------
$Id: STYLEGUIDE,v 1.5 1998-05-18 13:36:31 schmidt Exp $
------------------------------------------------------------