source: git/doc/STYLEGUIDE @ 8a929c

spielwiese
Last change on this file since 8a929c was c3af96, checked in by Hans Schoenemann <hannes@…>, 14 years ago
fix lusolve doc git-svn-id: file:///usr/local/Singular/svn/trunk@12890 2c84dea3-7e68-4137-9b89-c4e89433aadc
  • Property mode set to 100644
File size: 10.1 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+ Multicolumn tables: Rows of multicolumn tables need to go in one
52  line, otherwise texi2html 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+ keine latex-Konstrukte in @tex.. @end tex,
74  also z.B. kein \begin{..}...\end{..}, etc.:
75  hier darf nur auftauchen, was sowohl von tex als auch von latex
76  verstanden wird
77
78* Notationen *
79==============
80
81+ Schreibweise von Singular:
82    im Text: @sc{Singular}
83    in Singular-Kommentaren von Singular-Beispielen: SINGULAR
84    in Ueberschriften: SINGULAR
85
86+ Alle Singular-Befehle und -Variablen werden im Style @code
87  geschrieben:
88    @code{std}, @code{TRACE}
89
90+ Singular-Typen werden NICHT im Style @code geschrieben:
91    int, intmat
92
93+ Tasten, die man druecken muss, werden im Style @code geschrieben.
94  Die Control-Taste wird als CTRL abgekuerzt:
95    @code{CTRL-A}
96  Fuer RETURN, SPACE, etc, sollte @key{RETURN} verwendet werden.
97  (die html-UMsetzung hat Schwierigkeiten mit <SPACE> etc.)
98
99+ Gross/Kleinschreibung von Ueberschriften: Das erste Wort wird gross
100  geschrieben, alle anderen klein. Ausnahme: Wenn das erste Wort ein
101  reserviertes Wort von Singular ist, wird es so geschrieben, wie man
102  es in Singular schreibt:
103    Functions and system variables
104    int related functions
105    TRACE
106
107+ Die Funktionsweise von Funktionen (vor allem im Kapitel "Functions", aber
108  auch z.B. Kommandozeilen-Optionen, etc.)  wird in der dritten Person
109  beschrieben. Sie fangen mit einem Kleinbuchstaben an und schliessen mit
110  einem Punkt.  Bitte vollstaendige Saetze formulieren.
111
112    npars: returns the number of ring parameters.
113
114  Statt "will be" wird "is" verwendet:
115
116    the result is a standard basis (statt will be a standard basis)
117
118+ Fuer Kardinalzahlen: 0th, 1st, 2nd, i-th n-th
119
120
121
122* Schreibweisen *
123=================
124
125+ "standard basis" statt "standardbasis"
126
127+ "basering" statt "base ring"
128
129+ "Groebner" (ohne Umlaut)
130
131+ "I/O" statt "i/o"
132
133+ Meistens verwenden wir den Begriff "monomial ordering".
134
135+ "Computer Algebra" statt "computer algebra"
136
137+ Konstrukte wie "the ideal/module is..." vermeiden. Stattdessen etwa
138  "the ideal, resp.@: module, is..." schreiben.
139
140+ non-zero, zero-dimensional, zero-set: use hyphen; Plural of zero:
141  zeros (instead of zeroes)
142
143+ Zum Englischen: "i.e.", "e.g.", "for example", "that is",
144  "resp. ..."  usw. werden immer in Kommas eingebettet:
145    @sc{Singular}, for example, has the ...
146  Nach einem Doppelpunkt schreiben wir klein weiter:
147    Purpose: computes the dimension.
148
149+ Die pers"onliche Anrede des Lesers vermeiden.  Insbesondere die Worte
150  `you', `your', etc. vermeiden.
151
152* Singular Beispiele und libraries *
153====================================
154
155* generally, use @samllexample for (code) examples
156
157+ Ist der Kommentar zu einem Kommando in einem Beispiel, das von Singular
158  gerechnet werden soll, laenger als eine Zeile, muss das Kommando in der
159  untersten Zeile des Kommentars stehen (sonst wird in spaeter die
160  Singular-Ausgabe zwischen den Kommentar und das Kommando geschoben):
161@smallexample
162@c example
163  ring r;
164                 // the following option leads to some useful output
165  option(prot);  // during the Groebner basis computation.
166@c example
167@end smallexample
168
169+ Bei Beispielen, die nicht wirklich von doc2tex gerechnet, muss nach dem
170  @expansion ein Leerzeichen kommen, und geschweifte Klammern muessen
171  gequoted werden mit @:
172@smallexample
173int i=3;
174    // Kommentare ueber mehere Zeilen duerfen natuerlich
175i;  // mit Leerzeichen beginnen.
176@{@} // quote von geschweiften Klammern
177@expansion{} 3
178@end smallexample
179
180+ Beim Schreiben von Singular-Beispielen (insbesondere von
181  Kommentaren) bitte darauf achten, dass die Zeilen nicht zu breit
182  werden. (Sonst bekommt man "overfull hbox"-Meldungen um die Ohren
183  geschmissen.)
184
185+ Hilfe-Texte in Libraries: keine TAB's verwenden
186
187* Cross-Referenzen *
188====================
189
190+ es gibt drei Type von Cross-Referenzen (erste Zeile - Beispiel,
191  zweite Zeile - Resultat in Info, dritte Zeile - Resultat in TeX):
192
193
194  @xref      fuer den Anfang eines Satzes
195
196             @xref{Tropical Storms}, for more info.
197             *Note Tropical Storms::, for more info.
198             See Section 3.1 [Tropical Storms], page 24, for more info.
199
200  @ref       fuer den Ende eines Satzes
201
202             For more information, see @ref{Hurricanes}.
203             For more information, see *Note Hurricanes::.
204             For more information, see Section 8.2 [Hurricanes], page 123.
205
206  @pxref     fuer geklammerte Referenzen
207
208             ... storms cause flooding (@pxref{Hurricanes}) ...
209             ... storms cause flooding (*Note Hurricanes::) ...
210             ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...
211
212+ @xref und @ref *muessen* immer von einem Komma oder einem Punkt
213  oder einem Semikolon abgeschlossen werden.  Wie oben aufgefuehrt, sollte
214  @xref immer am Satzanfang stehen, @ref dagegen immer am Satzende.
215  Ausnahmen sind Listen von @ref's, wie unten beschrieben.
216
217+ @pxref darf nur innerhalb einer Klammer auftauchen.  Und zwar nur ein
218  einzelnes, keine Liste von @pxref's.
219
220+ mit der neuen Version von doc2tex kann (soll) man Listen von
221  Cross-Referenzen wie folgt schreiben:
222    @c ref
223    See
224    @ref{std};
225    @ref{stdfac};
226    @ref{stdhilbert}.
227    @c ref
228  Daraus wird dann automatisch ein Menue fuer die info-Files erzeugt.
229  (Man kann sich also das "@menu * std:: ...  @end menu" sparen.)
230  Bitte pro Zeile nur *eine* Referenz notieren und das `See'
231  in eine eigene Zeile packen.  Das macht die Sache
232  uebersichtlicher.  Ausserdem kann man die Referenzen dann
233  leichter im Editor handhaben (loeschen, alphabetisch
234  sortieren).
235  Die Referenzen bitte alphabetisch sortieren und mit einem Semikolon
236  trennen.
237
238* Index, Anchors*
239==================
240+ Do not hesitate to insert many index entries. Each index entries
241  needs to be written on one line. For one topic, insert different
242  formulation of the index entries. For example:
243@cindex The online help system
244@cindex online help
245@cindex help, online help system
246  Generally, if an index topic needs to be specified further, mention
247  the general topic first, separated by comma, and followed by
248  specialization (like "help, online help system").
249
250+ Use the @anchor{label} construct, to set arbitraty labels, to which
251  you can refer to with @ref{label}. For example:
252@anchor{option(prot);}
253  Put the @anchor before the explained topic, otherwise the html
254  display might cut the first line(s) of the explained topic.
255
256
257
258* Umlaute *
259===========
260@"o                 "o      umlaut accent
261@'o                 'o      acute accent
262@,{c}               c,      cedilla accent
263@=o                 =o      macron/overbar accent
264@^o                 ^o      circumflex accent
265@`o                 `o      grave accent
266@~o                 ~o      tilde accent
267@dotaccent{o}       .o      overdot accent
268@H{o}               ''o     long Hungarian umlaut
269@ringaccent{o}      *o      ring accent
270@tieaccent{oo}      [oo     tie-after accent
271@u{o}               (o      breve accent
272@ubaraccent{o}      o_      underbar accent
273@udotaccent{o}      o-.     underdot accent
274@v{o}               <o      hacek or check accent
275@ss{}               ss      es-zet or sharp S
276
277* allgemeines *
278===============
279
280+ Die Funktionalitaet von doc2tex ist im sourcecode ausfuehrlich
281  domkumentiert. Siehe doc2tex.pl - Vorspann.
282+ Innerhalb einer @tex-Umgebeung keine texinfo-Befehle (wie @ref) verwenden.
283
284+ neuere latex2html-Versionen erfordern das Aendern von
285  /usr/lib/latex2html/l2hconf.pm (und cfgcache.pm)
286  $DVIPSOPT = ' -Ppdf -E -r0'; -> $DVIPSOPT = ' -E -r0';
287  da sonst die PDF-Fonts benutzt werden, die fuer schware Unterstriche in den
288  Formal sorgen.
289------------------------------------------------------------
290$Id$
Note: See TracBrowser for help on using the repository browser.