Changeset 4d9437f in git for doc/STYLEGUIDE


Ignore:
Timestamp:
May 18, 1998, 2:53:39 PM (25 years ago)
Author:
Tim Wichmann <wichmann@…>
Branches:
(u'spielwiese', '8e0ad00ce244dfd0756200662572aef8402f13d5')
Children:
f0a99cb55197419ba1488feab6ed34d228a5e7ca
Parents:
2f786f772c07a297f5aeb1e84266fbeb9c80861d
Message:
* wichmann: reformatted and added new guidelines.


git-svn-id: file:///usr/local/Singular/svn/trunk@1812 2c84dea3-7e68-4137-9b89-c4e89433aadc
File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/STYLEGUIDE

    r2f786f r4d9437f  
     1* texinfo *
     2===========
     3
     4+ nach einer @table muss eine Leerzeile kommen, sonst steht im info-File
     5  die nachfolgende Zeile in der letzten Tabellenzeile mit drin.
     6
     7+ Das Argument von @cindex, @chapter, @section und @subsection darf
     8  nicht in geschweiften Klammern stehen, auch wenn es Leerzeichen
     9  enthaelt. (Das Argument geht bis zum Ende der Zeile.)
     10    @cindex Procedures
     11    @section Getting started
     12
     13+ Taucht ein Punkt innerhalb eines Satzes auf (z.B. als Ende einer
     14  Abkuerzung), so sollte darauf ein @: folgen. Sonst erscheint im
     15  Ausdruch ein zu grosser Abstand zum nachfolgenden Wort:
     16    compute w.r.t.@: a wellordering
     17    a Groebner resp.@: standard basis
     18
     19+ Die Zeichen @ und { und } muessen in texinfo mit @ "gequoted"
     20  werden (nicht mit Backslash!).
     21  Der Backslash muss nicht gequoted werden:
     22    @  muss als  @@  geschrieben werden
     23    {  muss als  @{  geschrieben werden
     24    }  muss als  @}  geschrieben werden
     25    \  wird als  \   geschrieben
     26  ACHTUNG: Dies gilt natuerlich nicht in Beispielen, die von doc2tex
     27  gelesen und in Singular verarbeitet werden! Dort duerfen die Zeichen
     28  nicht gequoted werden, das macht doc2tex alleine. Dies gilt insbesondere
     29  auch fuer Dateien, die ueber @c include eingelesen werden.
     30
     31+ Bei Aenderung von @node-Namen daran denken, dass der entsprechende Name
     32  auch im vorherigen und naechsten @node geaendert werden muss.
     33  Bei Aenderung von (Sub)sections daran denken, die Menues auf den neuen
     34  Stand zu bringen.
     35  Fehlerhafte @node- und @menu-Strukturen sieht man, wenn man singular.hlp
     36  erzeugt.
     37
     38+ bislang wurde von texinfo nach einem @tex Kommando zu viel space
     39  eingesetzt. Der Fehler ist im texinfo behoben. Man kann nun also auch
     40  mitten in einem Satz auf @tex umschalten, ohne etwas wie \noindent
     41  einsetzen zu muessen.
     42
     43* Notationen *
     44==============
     45
    146+ Schreibweise von Singular:
    247    im Text: @sc{Singular}
    … …  
    1156    int, intmat
    1257
    13 + Das Argument von @cindex, @chapter, @section und @subsection darf
    14   nicht in geschweiften Klammern stehen, auch wenn es Leerzeichen
    15   enthaelt. (Das Argument geht bis zum Ende der Zeile.)
    16     @cindex Procedures
    17     @section Getting started
     58+ Tasten, die man druecken muss, werden im Style @code geschrieben.
     59  Die Control-Taste wird als CTRL abgekuerzt:
     60    @code{CTRL-A}
    1861
    1962+ Gross/Kleinschreibung von Ueberschriften: Das erste Wort wird gross
    … …  
    2568    TRACE
    2669
    27 + Die Zeichen @ und { und } muessen in texinfo mit @ "gequoted"
    28   werden (nicht mit Backslash!).
    29   Der Backslash muss nicht gequoted werden:
    30     @  muss als  @@  geschrieben werden
    31     {  muss als  @{  geschrieben werden
    32     }  muss als  @}  geschrieben werden
    33     \  wird als  \   geschrieben
     70+ Die Funktionsweise von Funktionen (vor allem im Kapitel "Functions")
     71  wird in der dritten Person beschrieben. Statt "will be" wird "is"
     72  verwendet:
     73    vdim: returns the vector space dimension ....
     74    the result is a standard basis (statt will be a standard basis)
    3475
    35 + Tasten, die man druecken muss, werden im Style @code geschrieben.
    36   Die Control-Taste wird als CTRL abgekuerzt:
    37     @code{CTRL-A}
     76* Schreibweisen *
     77=================
    3878
    39 + der basering heisst "basering" und nicht "base ring".
     79+ "standard basis" statt "standardbasis"
     80
     81+ "basering" statt "base ring"
     82
     83+ "Groebner" (ohne Umlaut)
     84
     85+ "I/O" statt "i/o"
     86 
     87+ Meistens verwenden wir den Begriff "monomial ordering".
     88
     89+ Konstrukte wie "the ideal/module is..." vermeiden. Stattdessen etwa
     90  "the ideal resp.@: module is..." schreiben.
     91
     92+ Zum Englischen (Dank an Olaf und Christian):
     93  "i.e.", "e.g.", "for example", "that is" usw. werden immer in Kommas
     94  eingebettet:
     95    @sc{Singular}, for example, has the ...
     96  Nach einem Doppelpunkt schreiben wir klein weiter:
     97    Purpose: computes the dimension.
     98
     99* Singular Beispiele und libraries *
     100====================================
     101
     102+ Die Kommandozeilen in einem Beispiel beginnen mit zwei Leerzeichen:
     103@example
     104  ring r;
     105  ideal i=x,y;
     106@end example
     107
     108+ Ist der Kommentar zu einem Kommando in einem Beispiel, das von Singular
     109  gerechnet werden soll, laenger als eine Zeile, muss das Kommando in der
     110  untersten Zeile des Kommentars stehen (sonst wird in spaeter die
     111  Singular-Ausgabe zwischen den Kommentar und das Kommando geschoben):
     112  @example
     113  @c example
     114    ring r;
     115                   // the following option leads to some usefule output     
     116    option(prot);  // during the Groebner basis computation.
     117  @c example
     118  @end example
     119
     120+ Bei Beispielen, die nicht wirklich von doc2tex gerechnet, muss nach dem
     121  @expansion ein Leerzeichen kommen:
     122  @example
     123    int i=3; i;
     124    @expansion{} 3
     125  @end example
     126
     127+ Beim Schreiben von Singular-Beispielen (insbesondere von
     128  Kommentaren) bitte darauf achten, dass die Zeilen nicht zu breit
     129  werden. (Sonst bekommt man "overfull hbox"-Meldungen um die Ohren
     130  geschmissen.)
     131
     132+ Hilfe-Texte in Libraries: keine TAB's verwenden
     133
     134* Cross-Referenzen *
     135====================
    40136
    41137+ mit der neuen Version von doc2tex kann (soll) man Cross-Referenzen
    … …  
    54150  leichter im Editor handhaben (loeschen, alphabetisch
    55151  sortieren).
    56   Die Referenzen bitte alphabetisch sortieren.
     152  Die Referenzen bitte alphabetisch sortieren und mit einem Semikolon
     153  trennen.
    57154
    58 + Referenzen immer mit einem Komma oder Punkt abschliessen (z.B.
    59   @xref{foo}, for a description of foo.
     155+ Referenzen immer mit einem Komma oder Punkt abschliessen:
     156    @xref{foo}, for a description of foo.
    60157
    61158+ Eher @xref als @ref verwenden, da @ref im Info-file nicht so toll
    62159  aussieht.  Folgendes ist aber ok:
    63160    blah blah blah (@ref{blahblahblah}).
    64 
    65 + Beim Schreiben von Singular-Beispielen (insbesondere von
    66   Kommentaren) bitte darauf achten, dass die Zeilen nicht zu breit
    67   werden. (Sonst bekommt man "overfull hbox"-Meldungen um die Ohren
    68   geschmissen.)
    69 
    70 + Zum Englischen (Dank an Olaf):
    71   "i.e.", "e.g.", "for example", "that is" usw. werden immer in Kommas
    72   eingebettet:
    73     @sc{Singular}, for example, has the ...
    74   Nach einem Doppelpunkt schreiben wir klein weiter:
    75     Purpose: computes the dimension.
    76 
    77 * Hilfe-Texte in Libraries: keine TAB's verwenden
     161 
    78162------------------------------------------------------------
    79 $Id: STYLEGUIDE,v 1.3 1998-05-15 12:00:41 schmidt Exp $
     163$Id: STYLEGUIDE,v 1.4 1998-05-18 12:53:39 wichmann Exp $
    80164------------------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.