source: git/doc/STYLEGUIDE @ 58f1df7

spielwiese
Last change on this file since 58f1df7 was 609ba11, checked in by Olaf Bachmann <obachman@…>, 25 years ago
* use smallexample for examples git-svn-id: file:///usr/local/Singular/svn/trunk@3254 2c84dea3-7e68-4137-9b89-c4e89433aadc
  • Property mode set to 100644
File size: 8.5 KB
Line 
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+ Fuer Aestheten: anstatt der Quotes "..." die TeX Quotes verwenden
20  ``...''.
21
22+ Die Zeichen @ und { und } muessen in texinfo mit @ "gequoted"
23  werden (nicht mit Backslash!).
24  Der Backslash muss nicht gequoted werden:
25    @  muss als  @@  geschrieben werden
26    {  muss als  @{  geschrieben werden
27    }  muss als  @}  geschrieben werden
28    \  wird als  \   geschrieben
29  ACHTUNG: Dies gilt natuerlich nicht in Beispielen, die von doc2tex
30  gelesen und in Singular verarbeitet werden! Dort duerfen die Zeichen
31  nicht gequoted werden, das macht doc2tex alleine. Dies gilt insbesondere
32  auch fuer Dateien, die ueber @c include eingelesen werden.
33
34+ Bei Aenderung von @node-Namen daran denken, dass der entsprechende Name
35  auch im vorherigen und naechsten @node geaendert werden muss.
36  Bei Aenderung von (Sub)sections daran denken, die Menues auf den neuen
37  Stand zu bringen.
38  Fehlerhafte @node- und @menu-Strukturen sieht man, wenn man singular.hlp
39  erzeugt.
40
41+ bislang wurde von texinfo nach einem @tex Kommando zu viel space
42  eingesetzt. Der Fehler ist im texinfo behoben. Man kann nun also auch
43  mitten in einem Satz auf @tex umschalten, ohne etwas wie \noindent
44  einsetzen zu muessen.
45
46+ fuer Ellipsen (...) das Kommando @dots{} verwenden.  Eine Ellipse am Ende
47  eines Satzes mit @enddots{} schreiben.
48
49+ Email Adressen in @email{...} notieren, URL's in @url{...}
50
51+ Muticolumn tables: Rows of multicolumn tables need to go in one
52  line, otherwise exi2html chockes. Space beween rows with "empty"
53  rows (c.f. texi2html), i.e., with @item @tab @tab ....
54
55
56* tex *
57=======
58+ Use @math{...} as you would use $..$ in latex -- i.e., ANY
59  mathematical symbols should be within @math (or, @tex, if they
60  require special tex symbols)
61
62+ don't use \mbox, use \hbox, instead
63
64+ use \hbox only within math environment
65
66+ don't use any sophisticated tex commands (like \eqalign), restrict
67  yourself to command which latex understands, as well.
68
69+ no "@"-constructs within @tex ... @end tex
70
71+ @tex and '@end tex' should always be on separate lines
72
73
74
75* Notationen *
76==============
77
78+ Schreibweise von Singular:
79    im Text: @sc{Singular}
80    in Singular-Kommentaren von Singular-Beispielen: SINGULAR
81    in Ueberschriften: SINGULAR
82
83+ Alle Singular-Befehle und -Variablen werden im Style @code
84  geschrieben:
85    @code{std}, @code{TRACE}
86
87+ Singular-Typen werden NICHT im Style @code geschrieben:
88    int, intmat
89
90+ Tasten, die man druecken muss, werden im Style @code geschrieben.
91  Die Control-Taste wird als CTRL abgekuerzt:
92    @code{CTRL-A}
93
94+ Gross/Kleinschreibung von Ueberschriften: Das erste Wort wird gross
95  geschrieben, alle anderen klein. Ausnahme: Wenn das erste Wort ein
96  reserviertes Wort von Singular ist, wird es so geschrieben, wie man
97  es in Singular schreibt:
98    Functions and system variables
99    int related functions
100    TRACE
101
102+ Die Funktionsweise von Funktionen (vor allem im Kapitel "Functions", aber
103  auch z.B. Kommandozeilen-Optionen, etc.)  wird in der dritten Person
104  beschrieben. Sie fangen mit einem Kleinbuchstaben an und schliessen mit
105  einem Punkt.  Bitte vollstaendige Saetze formulieren.
106 
107    npars: returns the number of ring parameters.
108
109  Statt "will be" wird "is" verwendet:
110
111    the result is a standard basis (statt will be a standard basis)
112
113
114* Schreibweisen *
115=================
116
117+ "standard basis" statt "standardbasis"
118
119+ "basering" statt "base ring"
120
121+ "Groebner" (ohne Umlaut)
122
123+ "I/O" statt "i/o"
124 
125+ Meistens verwenden wir den Begriff "monomial ordering".
126
127+ "Computer Algebra" statt "computer algebra"
128
129+ Konstrukte wie "the ideal/module is..." vermeiden. Stattdessen etwa
130  "the ideal resp.@: module is..." schreiben.
131
132+ non-zero, zero-dimensional, zero-set: use hyphen; Plural of zero:
133  zeros (instead of zeroes)
134
135+ Zum Englischen: "i.e.", "e.g.", "for example", "that is",
136  "resp. ..."  usw. werden immer in Kommas eingebettet:
137    @sc{Singular}, for example, has the ...
138  Nach einem Doppelpunkt schreiben wir klein weiter:
139    Purpose: computes the dimension.
140
141+ Die pers"onliche Anrede des Lesers vermeiden.  Insbesondere die Worte
142  `you', `your', etc. vermeiden.
143
144* Singular Beispiele und libraries *
145====================================
146
147* generally use @samllexample for (code) examples
148
149* Die Kommandozeilen in einem Beispiel, das nicht von doc2tex
150  gerechnet wird, beginnen NICHT MEHR mit zwei Leerzeichen:
151@smallexample
152ring r;
153ideal i=x,y;
154@end smallexample
155
156* Beispiele, die von doc2tex gerechnet werden, muessen weiterhin mit
157  zwei Leerzeichen beginnen. Diese beiden Leerzeichen werden auto-
158  matisch von doc2tex gestrichen.
159  Dieses Verhalten wird sich nach Mittwoch aendern. Ab dann darf kein
160  Beispiel mit Leerzeichen beginnen. Aus Zeitgruenden verwenden wir
161  im Moment den "hack" mit doc2tex.
162
163+ Ist der Kommentar zu einem Kommando in einem Beispiel, das von Singular
164  gerechnet werden soll, laenger als eine Zeile, muss das Kommando in der
165  untersten Zeile des Kommentars stehen (sonst wird in spaeter die
166  Singular-Ausgabe zwischen den Kommentar und das Kommando geschoben):
167@smallexample
168@c example
169  ring r;
170                 // the following option leads to some useful output     
171  option(prot);  // during the Groebner basis computation.
172@c example
173@end smallexample
174
175+ Bei Beispielen, die nicht wirklich von doc2tex gerechnet, muss nach dem
176  @expansion ein Leerzeichen kommen, und geschweifte Klammern muessen
177  gequoted werden mit @:
178@smallexample
179int i=3;
180    // Kommentare ueber mehere Zeilen duerfen natuerlich
181i;  // mit Leerzeichen beginnen.
182@{@} // quote von geschweiften Klammern
183@expansion{} 3
184@end smallexample
185
186+ Beim Schreiben von Singular-Beispielen (insbesondere von
187  Kommentaren) bitte darauf achten, dass die Zeilen nicht zu breit
188  werden. (Sonst bekommt man "overfull hbox"-Meldungen um die Ohren
189  geschmissen.)
190
191+ Hilfe-Texte in Libraries: keine TAB's verwenden
192
193* Cross-Referenzen *
194====================
195
196+ es gibt drei Type von Cross-Referenzen (erste Zeile - Beispiel,
197  zweite Zeile - Resultat in Info, dritte Zeile - Resultat in TeX):
198
199
200  @xref      fuer den Anfang eines Satzes
201
202             @xref{Tropical Storms}, for more info.
203             *Note Tropical Storms::, for more info.
204             See Section 3.1 [Tropical Storms], page 24, for more info.
205
206  @ref       fuer den Ende eines Satzes
207
208             For more information, see @ref{Hurricanes}.
209             For more information, see *Note Hurricanes::.
210             For more information, see Section 8.2 [Hurricanes], page 123.
211
212  @pxref     fuer geklammerte Referenzen
213
214             ... storms cause flooding (@pxref{Hurricanes}) ...
215             ... storms cause flooding (*Note Hurricanes::) ...
216             ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...
217
218+ @xref und @ref *muessen* immer von einem Komma oder einem Punkt
219  oder einem Semikolon abgeschlossen werden.  Wie oben aufgefuehrt, sollte
220  @xref immer am Satzanfang stehen, @ref dagegen immer am Satzende.
221  Ausnahmen sind Listen von @ref's, wie unten beschrieben.
222
223+ @pxref darf nur innerhalb einer Klammer auftauchen.  Und zwar nur ein
224  einzelnes, keine Liste von @pxref's.
225
226+ mit der neuen Version von doc2tex kann (soll) man Listen von
227  Cross-Referenzen wie folgt schreiben:
228    @c ref
229    See
230    @ref{std};
231    @ref{stdfac};
232    @ref{stdhilbert}.
233    @c ref
234  Daraus wird dann automatisch ein Menue fuer die info-Files erzeugt.
235  (Man kann sich also das "@menu * std:: ...  @end menu" sparen.)
236  Bitte pro Zeile nur *eine* Referenz notieren und das `See'
237  in eine eigene Zeile packen.  Das macht die Sache
238  uebersichtlicher.  Ausserdem kann man die Referenzen dann
239  leichter im Editor handhaben (loeschen, alphabetisch
240  sortieren).
241  Die Referenzen bitte alphabetisch sortieren und mit einem Semikolon
242  trennen.
243
244
245* allgemeines *
246===============
247
248+ Die Funktionalitaet von doc2tex ist im sourcecode ausfuehrlich
249  domkumentiert. Siehe doc2tex.c.
250
251------------------------------------------------------------
252$Id: STYLEGUIDE,v 1.11 1999-07-09 14:12:46 obachman Exp $
Note: See TracBrowser for help on using the repository browser.