Here's a list of requests, of things to do right when you modify the manual.
1:Make a local copy, and look at your changes before commiting! Do not make
-someone else fix your LaTeX boo-boos.
+someone else fix your Sphinx/rST boo-boos.
1:Run a spell checker over your changes before committing.
The most common spelling errors (in our manual) run two words together as one.
"Filesystem" is correctly "file system."
@@ -21,9 +21,9 @@
it is your job to check all other parts of the manual to make sure that there
are no references that depend on the label.
-{section: Here is a list of things that make your techical writer's job easier.}
+{section: Here is a list of things that make your technical writer's job easier.}
-1:Place line breaks at the end of sentences and phrases. Yes, this makes the file longer in terms of line numbers. But, it also makes editting easier, since changes are often made at the granularity of sentences.
+1:Place line breaks at the end of sentences and phrases. Yes, this makes the file longer in terms of line numbers. But, it also makes editing easier, since changes are often made at the granularity of sentences.
1:If possible, write using the present tense, with an active voice (not passive voice), and in the third person.
*::Active voice says "after the job executes" where the passive voice "after the job has executed" means the same thing.
*::"You" and "Your job" are examples of second person; third person examples are "the user that submits a job" and "the job."
@@ -36,39 +36,3 @@
*: _deprecate_ has cult-following status among those who use it. Unfortunately, the dictionary defines it with "to express disapproval of" or "depreciate."
*::_Karen deprecates the use of the word "deprecate"._ is a correct usage.
*::_Karen desperately wants to deprecate the word "deprecate" from the manual._ is an incorrect usage.
-
-{section: Use of LaTeX macros}
-
-For consistancy in our formatting throughout the entire manual, please use our
-LaTeX macros. The main set of macros is in the file =condor-macros.tex=.
-When trying to decide what (if any) LaTeX macro to use,
-attempt to use these as already used in other parts of the manual.
-
-A big no-no is to introduce your own LaTeX macro within whatever file you are
-working on.
-If you really need a new macro defined, place it in =condor-macros.tex=.
-
-{section: Here are some common uses.}
-
-*: Configuration macro names are identified with one of two LaTeX macros.
-\Macro{} automatically generates an index entry within the manual.
-\MacroNI{} does not generate an index entry. NI stand for No Index.
-When deciding which to use, err on the side of including too many index entries. But, if you use the macro's name more than once within the same paragraph or subsection, use \Macro{} the first time, and then use \MacroNI{} for the remainder. We do this so that we do not get multiple independent index entries pointing to the same paragraph. The LaTeX indexing tools do not collapse multiple entries for us.
-*: ClassAd names (both job and machine ClassAd names) are identified with \AdAttr{}.
-
-{section: misc}
-
-*: Font size for verbatim examples. Our examples within the manual that use a fixed-width font start and end with a
-{verbatim}
- \begin{verbatim}
- \end{verbatim}
-{endverbatim}
-To insure that the pdf and postscript versions of the manual do not cut off the ends of the longer lines, reduce the font size. Add two more LaTeX macros surrounding the example, such that the source appears as
-{verbatim}
- \footnotesize
- \begin{verbatim}
- The long line(s) of verbatim text here.
- \end{verbatim}
- \normalsize
-{endverbatim}
- What constitutes a "longer line" is debatable. Definitely include it for lines that have more than 60 characters, but err on the side of safety (nice pdf output) by adding this for all but the shortest (20 characters or less). The goal of this advise is that you (the developer) will not need to examine the pdf output to check for lines that get cut off.
