www/doc potentialauthors.html GNU-Press-stylegu...

[Yavor Doganov]

CVSROOT:        /web/www
Module name:    www
Changes by:     Yavor Doganov <yavor>   09/01/18 16:07:14

Modified files:
        doc            : potentialauthors.html 
Added files:
        doc            : GNU-Press-styleguide.pdf 
                         GNU-Press-styleguide.texi 

Log message:
        Move the GNU Press style guide to /doc and link to it.

CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/doc/potentialauthors.html?cvsroot=www&r1=1.17&r2=1.18
http://web.cvs.savannah.gnu.org/viewcvs/www/doc/GNU-Press-styleguide.pdf?cvsroot=www&rev=1.1
http://web.cvs.savannah.gnu.org/viewcvs/www/doc/GNU-Press-styleguide.texi?cvsroot=www&rev=1.1

Patches:
Index: potentialauthors.html
===================================================================
RCS file: /web/www/www/doc/potentialauthors.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- potentialauthors.html       12 Jan 2009 18:11:37 -0000      1.17
+++ potentialauthors.html       18 Jan 2009 16:07:12 -0000      1.18
@@ -47,6 +47,10 @@
 Project <a href="/prep/maintain/">Information for Maintainers</a>
 Manual</li>
 
+<li>A Draft GNU Press Style Guide
+(<a href="/doc/GNU-Press-styleguide.texi">Texinfo
+source</a>, <a href="/doc/GNU-Press-styleguide.pdf">PDF</a>)</li>
+
 <li><a href="/software/texinfo/manual/texinfo/">Texinfo
 Manual</a></li>
 
@@ -89,7 +93,7 @@
 <p>
 Updated:
 <!-- timestamp start -->
-$Date: 2009/01/12 18:11:37 $
+$Date: 2009/01/18 16:07:12 $
 <!-- timestamp end -->
 </p>
 </div>

Index: GNU-Press-styleguide.pdf
===================================================================
RCS file: GNU-Press-styleguide.pdf
diff -N GNU-Press-styleguide.pdf
Binary files /dev/null and /tmp/cvs6KHMeu differ

Index: GNU-Press-styleguide.texi
===================================================================
RCS file: GNU-Press-styleguide.texi
diff -N GNU-Press-styleguide.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ GNU-Press-styleguide.texi   18 Jan 2009 16:07:12 -0000      1.1
@@ -0,0 +1,632 @@
+\input texinfo       @c -*-texinfo-*-
address@hidden %** start of header
address@hidden styleguide.info
address@hidden GNU Style Guide
address@hidden setchapternewpage odd
address@hidden edition-major-minor-number 4.15
address@hidden
address@hidden finalout
address@hidden %** end of header
+
address@hidden
+ ## Summary of shell commands to create various output formats:
+
+    ## Info output
+    makeinfo --no-split --paragraph-indent=0 --verbose style.texi
+
+    ## DVI output
+    texi2dvi style.texi
+
+    ## HTML output
+    makeinfo --html --no-split --verbose style.texi
+
+    ## Plain text output
+    makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
+    --verbose --no-headers --output=style.txt style.texi
+
+    ## DocBook output
+    makeinfo --docbook --no-split --paragraph-indent=0 --verbose style.texi
+
+    ## XML output
+    makeinfo --xml --no-split --paragraph-indent=0 --verbose style.texi
+
address@hidden ignore
+
address@hidden
address@hidden 10
address@hidden @titlefont{A Style Guide for GNU Documentation}
address@hidden 12pt
address@hidden by Ron Hale-Evans
address@hidden 12pt
address@hidden Based largely on comments by Robert J. Chassell
address@hidden and Richard M. Stallman
address@hidden 0pt plus 1fill
address@hidden Copyright @copyright{} 2001 Free Software Foundation, Inc.
address@hidden titlepage
+
address@hidden
address@hidden Top, Basic points of style, (dir), (dir)
address@hidden A guide to writing documentation in the GNU style.
+
+Copyright @copyright{} 2001 Free Software Foundation, Inc.
address@hidden ifnottex
+
address@hidden
+* Basic points of style::       
+* Ordering your text::          
+* Code examples::               
+* Metaphors::                   
+* English usage::               
+* Texinfo usage::               
+* Format while writing::        
address@hidden menu
+
address@hidden Basic points of style, Ordering your text, Top, Top
address@hidden Basic points of style
+
address@hidden
+The goal of free GNU documentation is to help the users and developers
+of GNU software.  There is no need for you to provide examples for
+software running under other operating systems.  In particular, there
+is no need for you to provide examples for operating systems that take
+away your freedom.
+
address@hidden @bullet
address@hidden
+Show, don't just tell.  Use plenty of examples (but don't be
+overly redundant).
+
address@hidden
+Move slowly.  Do not impose too much of a cognitive load at once
+on the reader.
+
address@hidden
+Explain things in detail if you are writing a tutorial for a novice.
+Since one tends to under-explain anyway, pretend you are writing for
+an intelligent person who lives in an undeveloped country and is
+unfamiliar with the technology you are explaining.
+
address@hidden
+Don't say too little.  If you cannot include enough information on a
+topic to do more than tantalize a novice, omit it entirely.
+
address@hidden
+Do not assume the reader has specific knowledge of mathematics or
+computer science when it is possible she doesn't.  You may have to
+explain what an integer is or what a byte is, at least at the level of
+a tutorial.
+
address@hidden
+Explain your value judgments.  For example, if you say a code snippet
+is or is not ``useful'', explain @emph{why} it is or is not.  Value
+judgments can only be formed by people with knowledge of the relevant
+subject, and if the reader had the knowledge you use to form your
+judgments, she probably wouldn't need to read your documentation!
+
address@hidden
+If necessary, repeat yourself, especially if the information you are
+repeating is important and might be missed the first time.  Also, if
+your reader is unlikely to remember a minor point that is nevertheless
+important to understand a major one, it is acceptable to repeat the
+information.
+
address@hidden
+Avoid editorializing, either about things outside the text (``As we
+know, every operating system but GNU sucks''), or about the text
+itself (``At last, we can address@hidden'').
+
address@hidden
+Design your text for a blind person; this is a good discipline.
+Documents, especially web pages, turn out much better.  When you want
+to know how a document will sound to a blind person, you can run it
+through Festival or Emacspeak.
+
address@hidden
+Diagrams are sometimes helpful.  Similarly, tables and lists of
+categories (variable types, types of operator, etc.) can help the
+reader encompass a large amount of information without a lot of
+superfluous connective text.
+
address@hidden
+Think of problems the reader might encounter --- ``gotchas'' that you
+might have experienced yourself --- then point them out.  For example,
+in C and C++, point out the difference between @code{=} and @code{==}.
+
address@hidden
+Explain conventions.  Note that software programming and usage often
+relies on conventions that are not obvious.  For example, a @samp{0}
+return code in a C program signifies ``zero errors''.  It is good to
+explain a convention such as this.
+
address@hidden
+Always tell people how to pronounce code when you introduce new
+terms. For example, if you are explaining pointers, tell the reader
+that @code{*my_ptr} can be pronounced ``the contents of the memory
+location @code{my_ptr}.''  The idea is to teach those who sound things
+out when reading to pronounce code the right way, rather than to come
+up with an idiosyncratic, personal method of reading, which can hurt
+their ability to learn the language.
+
+People who do not pronounce words, but depend entirely upon
+visualization, will not care much for this, but will not be hurt.
+Indeed, they will benefit, since they need to learn pronunciation in
+order to talk with other programmers.
+
address@hidden
+Qualify your statements.  Don't simply say, for example,
+``Parameters must have their types declared.''  Must @emph{all}
+parameters have their types declared?  If so, say so; if not, state
+which parameters must have their types declared and which must not;
+and give examples where necessary.
address@hidden itemize
+
address@hidden Ordering your text, Code examples, Basic points of style, Top
address@hidden Ordering your text
+
address@hidden
+Write about first things first.
+
address@hidden @bullet
address@hidden
+Write about the most important things in a section first.  You may
+want to give each its own subsection.  Don't make the mistake of
+writing, ``Blah, blah, and blah.  Oh, and by the way, this is really
+important: @dots{}''
+
address@hidden
+Put important notes to the reader in subsections of their own.
+This tells the reader the notes  really are important.
+
+While ``first things first'' usually applies, in some cases, the very
+end of a section is the best place for an important note, perhaps
+prefixed with @samp{@@address@hidden:@}}.  People tend to remember
+best the things they are shown first and last. Also, an important note
+can sometimes tie up a section very nicely.
+
address@hidden
+Order the information in your nodes from simple to complex.
+
address@hidden
+Don't use terms without defining them, at least in a brief,
+preliminary way.  Do not use them @emph{in the process of} defining
+them.  Here, for example, is a classic error: @samp{This variable can
+take only @@address@hidden address@hidden: true and false.}
+
address@hidden
+Make your assumptions clear @emph{before} you use them.  For example,
+if you assume that the reader knows basic trigonometry, say so before
+you launch into an example involving it.  You might also give pointers
+to where the reader could @emph{learn} about the subject in question.
+
address@hidden 1500
address@hidden
+Recursion and nested data structures are difficult.  Your text can
+easily get out of control.  Be extra careful to phrase your
+explanations clearly so the reader does not end up in a tangle.
+
address@hidden @strong
address@hidden Bad:
+``All variables local to a block are invisible outside
+their block, but visible within every block their block contains.''
+
address@hidden Good:
+``A local variable is visible within its own block and
+the ones that block contains, but invisible outside its own block.''
address@hidden table
+
address@hidden
+If your chapter is titled ``About foo and
+bar'', do not discuss your topics in the order ``bar'' and ``foo''.  Be
+parallel and consistent throughout the section in question.  This may
+mean you will have to order your text carefully in advance, but your
+readers will thank you.
+
address@hidden
+If you have two tables or lists of information that discuss the
+same items, combine them!  Don't make the reader flip from one to the
+other, correlating them in her head.
+
address@hidden
+Don't combine different topics in the same paragraph or node.  If
+you want to start a new topic, start a new paragraph or a new node.
+
address@hidden
+After you have made an important point in a paragraph, end the
+paragraph and let the reader ``walk away with'' that information.
+Don't clutter the paragraph with details, trailing off into
+irrelevance; save the details for later.
+
address@hidden
+When you are explaining a feature of a program, it is often helpful to
+awaken the reader's interest by first outlining a problem the feature
+solves or a need it fulfills.  Write text that ``motivates'' the
+reader to understand why the feature is needed.  You should assume
+that most people will not themselves think that they need the feature
+ahead of time, and that when the feature is introduced, only the
+really smart readers will figure out for themselves why it is a good
+idea.
+
address@hidden itemize
+
address@hidden Code examples, Metaphors, Ordering your text, Top
address@hidden Code examples
+
address@hidden
+Examples should follow the GNU style.  Consult the @cite{GNU
+Coding Standards} for further information.
+
address@hidden @bullet
address@hidden
+Give sample output for code examples wherever possible.
+
address@hidden
+Don't waste the reader's time with frivolous examples that have no
+real use.  For example, in the @cite{GNU C Tutorial}, it was judged too
+frivolous to show the reader how to print out the values of pointers (of
+the pointers themselves, not the addresses pointed to), even though
+earlier editions of the book had done so.
+
address@hidden
+When you discuss a function, do not include the parentheses in
+its name unless you are illustrating a function call.  For example, use
address@hidden rather than @code{cos()}.
+
address@hidden
+In an example, snuggle code up to the @code{@@example} and
address@hidden@code{@@end example}} lines; do not insert blank lines between the
+lines containing the formatting commands and the lines containing the
+code.
+
address@hidden
+Always check your code examples by compiling and running them before
+including them in your text.  This applies even to small examples.
+Double-check your mathematical examples as well as your code.  Nothing
+will make your reader lose confidence in your documentation faster
+than catching you in a simple error.
+
address@hidden
+Use the present ``timeless'' tense when talking about what a code
+example does.  Example: ``The @code{foo} function takes an integer
+variable @code{bar} and multiplies it by 5.''
+
address@hidden
+Put ellipses inside dummy code blocks, unless you want to imply
+they are no-ops.
+
address@hidden
+In examples of code, use all-caps only for macros and the like that
+are normally written in uppercase letters.  Use lowercase letters for
+everything else.
+
address@hidden
+Don't use examples that will become dated.  You don't know how
+long your text will be read.  Example: If you are writing in the year
+2002, and you want to use an example of a variable containing a year,
+rather than creating a variable called @code{cur_year} and making it
+equal to @samp{2002}, it is better to create a variable called
address@hidden and make it equal to @samp{1969}.
+
address@hidden
+In your code examples, use variable names that are concrete rather
+than abstract.  Concrete names are less confusing.  For example, a
+variable called @code{cost_of_lunch} is better than one called
address@hidden or @code{foo}.  On the other hand, do not use
+variable names that are so concrete that the example itself takes over
+and the lesson it is supposed to convey is lost.
+
address@hidden
+Satisfy the reader's curiosity about whether alternate coding
+practices are possible, but make your recommendations clear.
address@hidden itemize
+
address@hidden Metaphors, English usage, Code examples, Top
address@hidden Metaphors
+
address@hidden
+People reason using metaphors.
+
address@hidden @bullet
address@hidden
+Develop your metaphors explicitly.  For example, if you say local
+variables are ``invisible'' outside their functions, explain that this
+usage stems from a metaphor in which functions are something like
+buildings and local variables are like people looking from one building
+to another.
+
address@hidden
+Jargon often has a metaphorical underpinning.  For example,
+pointers ``point to'' memory addresses.  It is helpful to explain these
+metaphorical underpinnings when introducing a jargon term.
+
address@hidden
+Explain where your metaphors fail.  For example, when explaining
+pointers in C, explain that while, with the same finger, you can point to
+anything you like in real life (whether it be animal, vegetable, or
+mineral) a given pointer can only point to a certain type of variable
+(only to integers or only to floats, for example).
+
address@hidden
+Use a metaphor consistently; do not mix metaphors.
+For example, when discussing local variables, do not at one point say
+they are ``invisible'' outside their functions and at another point
+say that they are ``nonexistent'' outside their functions.  Stick to
+one metaphor or the other.
+
+If you @emph{must} use more than one metaphor, introduce transitional
+material and explain how and why you are switching metaphors.
+
address@hidden
+Avoid idioms and implicit metaphors wherever possible.
+People translate GNU documentation into many different languages.
+English idioms such as ``this feature opens the door to the
+possibility of @dots{}'' only make more work for translators whose
+languages do not possess the idiom.
address@hidden itemize
+
address@hidden English usage, Texinfo usage, Metaphors, Top
address@hidden English usage
+
address@hidden
+!!! is it really true that early editions of `The Elements of Style'
+are now in the public domain?  I cannot find my copy to check when it
+was first copyrighted.  In the US, the recent change in law kept books
+that were published between 1923 and 1941 out of the public domain.
address@hidden ignore
+
address@hidden
+Consult good books on English style.  For example, a classic text is
address@hidden Elements of Style} by Strunk and White.  Early editions of
+it are now in the public domain and are therefore free in the GNU
+sense.
+
address@hidden
+Also consult the @cite{GNU Coding Standards}, which discusses
+documentation as well as code.
+
address@hidden @bullet
address@hidden
+Don't mention non-free software by name unless it is unavoidable.
+
address@hidden
+Refer to GNU more and Unix less.
+
+Always write ``GNU/Linux'', never just ``Linux'', unless you are
+only referring to the Linux kernel.
+
address@hidden
+Use ``illegal'' only for matters of the law and government.  For
+violations of the rules of C or other languages, use ``invalid''.
+
address@hidden
+Always address the reader as ``you''.  Example: ``If you want to
+display the diagram, press the @key{RET} key.''
+
address@hidden
+Use ``must'', ``should'', ``may'', and ``can'' appropriately.  Do not
+conflate them when discussing actions you must, should, may, or can
+perform while using software.
+
address@hidden
+Examples are not ``given'' but ``shown''.  Only
+useful stand-alone programs qualify as gifts.
+
address@hidden 1500
address@hidden
+``Kinds of'' and ``types of'' are followed by a singular noun.
+For example:
+
address@hidden @strong
address@hidden Bad:
+``kinds of computers'', ``types of variables''
+
address@hidden Good:
+``kinds of computer'', ``types of variable''
address@hidden table
+
address@hidden
+There should be no text between ``as follows'' and what is said to
+follow.
+
address@hidden 1500
address@hidden
+Be careful to separate English from C code (or the code of whatever
+computer language you are using).  For example, in the first example
+below, the English word ``or'' might be confused by the reader with
+the Boolean operator @sc{or}.
+
address@hidden @strong
address@hidden Bad:
address@hidden@@address@hidden address@hidden (or operator on Boolean values)}
+
address@hidden Good:
address@hidden@@address@hidden address@hidden (an operator on Boolean values)}
address@hidden table
+
address@hidden
+Failure to process negatives is a common problem in reading.  Phrase
+your text so that a reader is not likely to miss an important ``not''.
+Do not repeat the negative information in a manner that could make it
+appear positive.
+
address@hidden
+Distinguish computer science terms and jargon from the language of the
+reader's everyday experience.  For example, you may need to tell the
+reader that the Boolean value @code{true} is true and only true, while
+in real life ``true'' might mean ``only partly true'', as in ``that's
+a true story, although parts are exaggerated''.
+
address@hidden 1500
address@hidden
+Most people except LISP programmers dislike parentheses.  Use as
+few as possible.  If you can, avoid using parentheses in tables.
+
address@hidden @strong
address@hidden Bad:
+unary plus (example: @code{+5})
+
address@hidden Good:
+unary plus, example: @code{+5}
address@hidden table
+
address@hidden
+Use language precisely.  For example, when discussing C, a
+``declaration'' is not the same as a ``definition''.  Many distinct
+terms sound alike and are used in similar ways, but that is no excuse
+for @emph{you} to conflate them, or to fail to distinguish them for
+your readers.  Moreover, don't simply say that two terms are
+different, but explain their differences.
+
+Similarly, distinguish one use of a jargon word from another.  For
+example:  ``value of a variable'' vs. ``passing by value''.
address@hidden itemize
+
address@hidden Texinfo usage, Format while writing, English usage, Top
address@hidden Texinfo usage
+
address@hidden
+Please read the Texinfo manual through; it will do you good.
+
address@hidden @bullet
address@hidden
+Use @samp{@@code}, @samp{@@samp}, @samp{@@file}, etc. correctly;
+for clarification,
address@hidden
+see the @cite{Texinfo Manual}.
address@hidden iftex
address@hidden
+see the @cite{Texinfo Manual}.
address@hidden ifhtml
address@hidden
+see @ref{Top, , , texinfo, The Texinfo Manual}.
address@hidden ifinfo
+
address@hidden
+Use @samp{@@xref} properly; never use it in mid-sentence.
+
address@hidden
+To emphasize, use @samp{@@emph} or @samp{@@strong}, not all-caps.
+
address@hidden
+For meta-syntactic variables, use @samp{@@var}, not angle brackets.
+
address@hidden
+End every sentence with two spaces so Emacs can see where
+sentences begin and end.  (See
address@hidden
+the ``Sentences'' section in @cite{The GNU Emacs Manual},
address@hidden iftex
address@hidden
+the ``Sentences'' section in @cite{The GNU Emacs Manual},
address@hidden ifhtml
address@hidden
address@hidden, , The GNU Emacs Manual, emacs, The GNU Emacs Manual},
address@hidden ifinfo
+which describes convenient sentence-related commands.)
+
address@hidden
+Use @samp{@@group} to hold together examples that should stay all
+on one page.
+
+Note that the @code{@@group} command does not currently work with the
address@hidden@@table} command.  Instead, use the @code{@@need} command with
address@hidden@@table}.  Similarly, use the  @code{@@need} command before a
+plain text paragraph that introduces an example or list.
address@hidden
+(See the @cite{Texinfo Manual}.)
address@hidden iftex
address@hidden
+(See the @cite{Texinfo Manual}.)
address@hidden ifhtml
address@hidden
+(@xref{Top, , , texinfo, The Texinfo Manual}.)
address@hidden ifinfo
+
address@hidden
+Never use typesetting commands for markup!  Always use logical
+markup instead.  You gain nothing in Info by putting ``Important:'' in
+boldface.  Unless your reader uses an unusual stylesheet, you will not
+help Emacspeak, either.  Replace @samp{@@address@hidden:@}} with
address@hidden@@address@hidden:@}} so formatting software can figure out
+how to handle the markup appropriately.  The use of typesetting markup
+is the bane of the HTML world; logical markup works better, and one
+reason that XML was invented.
+
+The only legitimate use of a typesetting command in GNU
+documentation is to cause plain, explanatory text in a table or example
+to be in a Roman font.  Use the @code{@@r} command to do this.
+
address@hidden itemize
+
address@hidden Format while writing,  , Texinfo usage, Top
address@hidden Format As You Write
+
address@hidden
+Format your text as you write.  This eases your final cleanup.
+
address@hidden
+Then, at the end of your project, again check how your text will look
+in Info, on a Web page, and typeset for printing.  Listen to it as
+well; or, at at the very least, consider how it sounds when read out
+loud.
+
address@hidden @bullet
address@hidden
+As you write, make sure your file will compile as an Info document.
+In GNU Emacs, you can do the following:
+
address@hidden
address@hidden
+Run @kbd{C-c C-m C-b} (@code{makeinfo-buffer}), then
address@hidden
+run @kbd{C-u C-c C-u C-a} (which is @code{texinfo-all-menus-update},
+with a prefix argument); then
address@hidden
+fix the remaining errors, then
address@hidden
+repeat this sequence until there are no more errors.
address@hidden enumerate
+
address@hidden
+Run the spell-checker!
+
address@hidden
+When polishing the text, make sure your page layout is attractive; for
+example, make sure you don't use too much whitespace.  You can group
+chunks of text together with the @code{@@group} and @code{@@need}
+commands.
+
address@hidden 1500
address@hidden
+In tables and code examples, line up columns neatly:
+
address@hidden:}
address@hidden
+a: 1
+b :  2
+c:3
address@hidden smallexample
+
address@hidden:}
address@hidden
+a : 1
+b : 2
+c : 3
address@hidden smallexample
+
address@hidden
+When you email your manuscript to your editor, consider compressing it
+with @code{gzip} and sending it as a uuencoded or base-64 encoded
+attachment.  This will prevent it from being mangled in email.  Some
+email programs transform a @samp{From} at the start of a line to
address@hidden>From}.  Gzipped and encoded attachments are not vulnerable to
+this sort of corruption.  (Short documents without a @samp{From} at
+the start of a line do not need to be compressed and encoded.)
+
address@hidden
+As I said before, look at your text in all three major output formats:
+in Info, on a Web page, and typeset for printing.  In addition, listen
+to it; or else consider how it sounds when read out loud.
address@hidden itemize
+
address@hidden
+