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

# Contents of /trunk/writing.html

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 2 3 8 9 10 Contributing to the LaTeX2e unofficial reference manual 11 12 75 76 77 78 79

Contributing to the LaTeX reference manual

80

The LaTeX2e Unofficial Reference Manual 81 aims to provide a reference for the user-level commands of LaTeX. 82 For more information, see the 83 home page. 84

85 86 87

You can help

88

We welcome bug reports or suggestions of any kind. 89 Please email to 90 latexrefman@tug.org 91 (subscribe, 92 archive).

93 94

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 latex2e.texi 99 for comments prefixed with "xx". 100 That is how we note areas that need more work.

101 102

Or, you can look through 103 keeptrack.csv. 104 It lists all of the commands in the LaTeX source. 105 Each has a status: 106 done for commands already mentioned, 107 todo for ones that we will do, 108 notdoing for ones that we will not do (usually because they 109 are not user-level commands), 110 and other for uncharacterized commands. 111 Grab a todo command and have a whack, following the guidelines 112 below.

113 114 115

Write an entry

116

Each entry is different but over time we have worked out some 117 general guidelines. 118 A good example is the one for 119 \footnote.

120 121
122
• Begin with a synopsis. 123 It gives the syntax. 124 Here is \footnote's. 125
Synopsis, one of:
126  \footnote{text}
127  \footnote[number]{text}
128 Note that it lists separately the command version with and without 129 the optional number. 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.
• 133 134
• Follow with a one or two sentence 135 description. 136 The \footnote command description starts with 137 "Place a footnote text at the bottom of the current 138 page."
• 139 140
• Next is an example. 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.
• 145 146
• Then give a full explanation. 147 Say all you can reasonably say, including any gotcha's 148 (footnote discusses what happens inside a 149 minipage). 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 the TeX-LaTeX Stack Exchange, 158 texhax, 159 and 160 comp.text.tex). 161 If convenient, furnish any parameter values that are in the standard 162 classes. 163 For instance, \footnote has \footnoterule 164 and \footnotesep.
• 165 166
• Some entries end with more examples. 167 Following the full explanation, you may want to give 168 examples of any fine points.
• 169
170 171

Examples are particularly important since they are what most people 172 look for. 173 Here are a few guidelines: 174 (1) Test all your examples, no matter how small. 175 (2) Use best practices, both coding and typographic practices, 176 such as including the \, space in <\code>$\int x\, dx$. 177 (3) 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 "foo" and "bar." 181 And "baz" is right out. 182

183 184

186 187 188

Send it in

189

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 email the list. 193 We will mark it up for insertion in the document source.

194 195

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 directions 200 on our project page): 201 (i) install 202 Subversion, 203 (ii) create a convenient directory; here we illustrate with 204 /home/jim/src/latexrefman/, and 205 (iii) in that directory run 206 svn checkout http://svn.gnu.org.ua/sources/latexrefman/trunk 207 to fetch the subdirectory trunk/. 208 The document source is the single file trunk/latex2e.texi. 209 It is marked up in 210 Texinfo. 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 Texinfo manual 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 make 220 in the trunk 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.

224 225
226 227 228

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