source: git/doc/STYLEGUIDE @ 7af4737

* 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", 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)


* 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:
  "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, das nicht von doc2tex
  gerechnet wird, beginnen NICHT MEHR mit zwei Leerzeichen:
@example
ring r;
ideal i=x,y;
@end example

* Beispiele, die von doc2tex gerechnet werden, muessen weiterhin mit
  zwei Leerzeichen beginnen. Diese beiden Leerzeichen werden auto-
  matisch von doc2tex gestrichen. 
  Dieses Verhalten wird sich nach Mittwoch aendern. Ab dann darf kein
  Beispiel mit Leerzeichen beginnen. Aus Zeitgruenden verwenden wir
  im Moment den "hack" mit doc2tex.

+ 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 useful 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; 
    // Kommentare ueber mehere Zeilen duerfen natuerlich
i;  // mit Leerzeichen beginnen.
@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.)

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

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

+ Die Funktionalitaet von doc2tex ist im sourcecode ausfuehrlich 
  domkumentiert. Siehe doc2tex.c.

------------------------------------------------------------
$Id: STYLEGUIDE,v 1.8 1998-05-18 19:59:07 wichmann Exp $
------------------------------------------------------------