* 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{...} + Muticolumn tables: Rows of multicolumn tables need to go in one line, otherwise exi2html 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 * 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. + 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 * Die Kommandozeilen in einem Beispiel, das nicht von doc2tex gerechnet wird, beginnen NICHT MEHR mit zwei Leerzeichen: @smallexample ring r; ideal i=x,y; @end smallexample * 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): @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. * allgemeines * =============== + Die Funktionalitaet von doc2tex ist im sourcecode ausfuehrlich domkumentiert. Siehe doc2tex.c. ------------------------------------------------------------ $Id: STYLEGUIDE,v 1.11 1999-07-09 14:12:46 obachman Exp $