/ [latexrefman] / trunk / writing.html
To checkout: svn checkout http://svn.gnu.org.ua/sources/latexrefman/trunk/writing.html
Puszcza

Contents of /trunk/writing.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 816 - (show annotations)
Mon Jul 6 21:55:09 2020 UTC (10 months ago) by karl
File MIME type: text/html
File size: 9974 byte(s)
texinfo even better

1 <!DOCTYPE html>
2 <html>
3 <!-- This document is part of the LaTeX2e Unofficial Reference Manual
4 project. For information on the project, including license information, see
5 https://puszcza.gnu.org.ua/software/latexrefman.
6
7 2018-October Jim Hefferon, Karl Berry. Written -->
8 <head>
9 <meta charset="UTF-8">
10 <title>Contributing to the LaTeX2e unofficial reference manual</title>
11 <meta name="keywords" content="\name (LaTeX2e unofficial reference manual)">
12 <style type="text/css">
13 /* $Id: latex2e.css 690 2018-09-15 15:20:19Z jimhefferon $
14 Minor css for latexrefman. Public domain.
15 Originally written by Jim Hefferon and Karl Berry, 2018. */
16
17 /* So you can style for yourself */
18 @import url("/css/latexreflocal.css");
19
20 a.summary-letter {text-decoration: none}
21 blockquote.indentedblock {margin-right: 0em}
22 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
23 blockquote.smallquotation {font-size: smaller}
24 div.display {margin-left: 3.2em}
25 div.example {margin-left: 3.2em}
26 div.lisp {margin-left: 3.2em}
27 div.smalldisplay {margin-left: 3.2em}
28 div.smallexample {margin-left: 3.2em}
29 div.smalllisp {margin-left: 3.2em}
30 kbd {font-style: oblique}
31 pre.display {font-family: inherit}
32 pre.format {font-family: inherit}
33 pre.menu-comment {font-family: serif}
34 pre.menu-preformatted {font-family: serif}
35 pre.smalldisplay {font-family: inherit; font-size: smaller}
36 pre.smallexample {font-size: smaller}
37 pre.smallformat {font-family: inherit; font-size: smaller}
38 pre.smalllisp {font-size: smaller}
39 span.nolinebreak {white-space: nowrap}
40 span.roman {font-family: initial; font-weight: normal}
41 span.sansserif {font-family: sans-serif; font-weight: normal}
42 ul.no-bullet {list-style: none}
43 BODY {
44 margin-top: 1em;
45 margin-left: 1em; /* auto results in two-digit <ol> lost off left */
46 margin-right: 1em;
47 margin-bottom: 1em;
48 /* the idea is to use the whole window, unless it is ridiculously
49 wide, probably with too-small fonts, too. */
50 max-width: 64em;
51 }
52
53 /* Because we want @math{... @code ...} to be upright, not slanted,
54 and Texinfo won't fix it. */
55 code {font-style:normal; font-family:monospace; }
56
57 /* We put a link to our own home page at the bottom. */
58 div.referenceinfo {font-size:small;}
59
60 /* CSS for this page */
61 .listitem {font-weight: bold; margin-right: 0.6em; }
62 /* For TeX and LaTeX, Theresa O’Connor tess.oconnor.cx/2007/08/tex-poshlet */
63 /* Use as: <span class="latex">L<sup>a</sup>T<sub>e</sub>X</span> */
64 <!-- .tex sub, .latex sub, .latex sup {text-transform: uppercase; } -->
65 <!-- .tex sub, .latex sub {vertical-align: -0.5ex; -->
66 <!-- margin-left: -0.1667em; -->
67 <!-- margin-right: -0.125em; } -->
68 <!-- .tex, .latex, .tex sub, .latex sub {font-size: 1em; } -->
69 <!-- .latex sup {font-size: 0.85em; -->
70 <!-- vertical-align: 0.15em; -->
71 <!-- margin-left: -0.36em; -->
72 <!-- margin-right: -0.15em; } -->
73 .listitem {font-weight: bold; margin-right: 0.4em; }
74 </style>
75 </head>
76
77 <body lang="en">
78 <a name="top"></a>
79 <h2 class="section">Contributing to the LaTeX reference manual</h2>
80 <p>The <i>LaTeX2e Unofficial Reference Manual</i>
81 aims to provide a reference for the user-level commands of LaTeX.
82 For more information, see the
83 <a href="https://puszcza.gnu.org.ua/software/latexrefman">home page</a>.
84 </p>
85
86
87 <h3 class="section">You can help</h3>
88 <p id="emaillist">We welcome bug reports or suggestions of any kind.
89 Please email to
90 <code>latexrefman@tug.org</code>
91 (<a href="http://lists.tug.org/latexrefman/">subscribe</a>,
92 <a href="http://tug.org/pipermail/latexrefman/">archive</a>).</p>
93
94 <p>If you would like to contribute more systematically, that's great.
95 Reading through the document will turn up plenty of places where you can
96 make an improvement.
97 For example, you can search in the (sole) source file
98 <a href="http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.texi">latex2e.texi</a>
99 for comments prefixed with &quot;<tt>xx</tt>&quot;.
100 That is how we note areas that need more work.</p>
101
102 <p>Or, you can look through
103 <a href="http://svn.gnu.org.ua/viewvc/latexrefman/trunk/src/keeptrack.csv?view=markup"><code>keeptrack.csv</code></a>.
104 It lists all of the commands in the LaTeX source.
105 Each has a status:
106 <i>done</i> for commands already mentioned,
107 <i>todo</i> for ones that we will do,
108 <i>notdoing</i> for ones that we will not do (usually because they
109 are not user-level commands),
110 and <i>other</i> for uncharacterized commands.
111 Grab a <i>todo</i> command and have a whack, following the guidelines
112 below.</p>
113
114
115 <h3 name="styleguide" class="section">Write an entry</h3>
116 <p>Each entry is different but over time we have worked out some
117 general guidelines.
118 A good example is the one for
119 <a href="https://latexref.xyz/bs-footnote.html"><code>\footnote</code></a>.</p>
120
121 <ul>
122 <li><span class="listitem">Begin with a synopsis.</span>
123 It gives the syntax.
124 Here is <code>\footnote</code>'s.
125 <pre>Synopsis, one of:
126 \footnote{<i>text</i>}
127 \footnote[<i>number</i>]{<i>text</i>}</pre>
128 Note that it lists separately the command version with and without
129 the optional <i>number</i>.
130 It does not use square brackets to indicate options because that
131 would be using the brackets both as characters that appear in the
132 LaTeX input, and as metacharacters.</li>
133
134 <li><span class="listitem">Follow with a one or two sentence
135 description.</span>
136 The <code>\footnote</code> command description starts with
137 &quot;Place a footnote <i>text</i> at the bottom of the current
138 page.&quot;</li>
139
140 <li><span class="listitem">Next is an example.</span>
141 Give a common use, ideally one that helps explain why a person would use
142 this command.
143 It should be copy-and-pasteable because that is what people do
144 with reference material.</li>
145
146 <li><span class="listitem">Then give a full explanation.</span>
147 Say all you can reasonably say, including any gotcha's
148 (<code>footnote</code> discusses what happens inside a
149 <code>minipage</code>).
150 A reference is not a tutorial so you don't need to
151 start from first principles;
152 if something uses LR mode or involves some tricky stuff with glue
153 then just say that.
154 You might search the web for questions that people have asked about
155 this command, to see if there are fine points that the entry should
156 cover (good sources are
157 <a href="https://tex.stackexchange.com/">the TeX-LaTeX Stack Exchange</a>,
158 <a href="http://tug.org/mailman/listinfo/texhax"><code>texhax</code></a>,
159 and
160 <a href="https://groups.google.com/forum/#!forum/comp.text.tex"><code>comp.text.tex</code></a>).
161 If convenient, furnish any parameter values that are in the standard
162 classes.
163 For instance, <code>\footnote</code> has <code>\footnoterule</code>
164 and <code>\footnotesep</code>.</li>
165
166 <li><span class="listitem">Some entries end with more examples.</span>
167 Following the full explanation, you may want to give
168 examples of any fine points.</li>
169 </ul>
170
171 <p>Examples are particularly important since they are what most people
172 look for.
173 Here are a few guidelines:
174 (1)&nbsp;Test all your examples, no matter how small.
175 (2)&nbsp;Use best practices, both coding and typographic practices,
176 such as including the <code>\,</code> space in <\code>$\int x\, dx$</code>.
177 (3)&nbsp;Keep it brief but make it interesting, or at least sensible.
178 If you are illustrating a formula then use an actual formula.
179 For text, use an example from an actual document if reasonable but
180 in any event try to minimize &quot;foo&quot; and &quot;bar.&quot;
181 And &quot;baz&quot; is right out.
182 </p>
183
184 <p>Finally, of course we must follow the source license with respect to
185 quoting and attribution.</p>
186
187
188 <h3>Send it in</h3>
189 <p>The easiest way to start is to put your suggestion in plain text
190 (or Texinfo is even better, if you wrote it that way; but Texinfo is
191 not required)
192 and <a href="#emaillist">email the list</a>.
193 We will mark it up for insertion in the document source.</p>
194
195 <p>Making a ready-to-insert entry is more involved and maybe we should
196 have a conversation when you want to do that, but here is an overview.
197 First get the files
198 (see also the
199 <a href="https://puszcza.gnu.org.ua/svn/?group=latexrefman">directions</a>
200 on our project page):
201 (i)&nbsp;install
202 <a href="https://subversion.apache.org/"><i>Subversion</i></a>,
203 (ii)&nbsp;create a convenient directory; here we illustrate with
204 <code>/home/jim/src/latexrefman/</code>, and
205 (iii)&nbsp;in that directory run
206 <code>svn checkout http://svn.gnu.org.ua/sources/latexrefman/trunk</code>
207 to fetch the subdirectory <code>trunk/</code>.
208 The document source is the single file <code>trunk/latex2e.texi</code>.
209 It is marked up in
210 <a href="https://www.gnu.org/software/texinfo/">Texinfo</a>.
211 Next, decide where to put your new entry, and
212 then copy the one next to that and edit to suit.
213 (The
214 <a href="https://www.gnu.org/software/texinfo/manual/texinfo/">Texinfo manual</a>
215 has all the information but we try to stay away from any advanced stuff.)
216 Besides inserting the entry,
217 you must also put a pointer to that entry into a menu.
218 Again here find the pointer to the adjacent entry, and copy and edit.
219 Finally, compile to output by running <code>make</code>
220 in the <code>trunk</code> directory.
221 Once you have gotten used to marking up entries, if you
222 want write access to the repository then let us know on the mailing list.
223 We'll see about an account.</p>
224
225 <hr/>
226 <div class='referenceinfo'> <a href='https://latexref.xyz/'> <i>Unofficial LaTeX2e reference manual</i></a></div>
227 </body>
228 </html>

Send suggestions and bug reports to Sergey Poznyakoff
ViewVC Help
Powered by ViewVC 1.1.20