From: Graham Percival Date: Sun, 11 Nov 2007 22:01:21 +0000 (-0800) Subject: Split policy into writing- and policy. X-Git-Tag: release/2.11.35-1~41^2~3^2~3 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=27a46340a5abf5e6759650d4bb8b68779869f768;p=lilypond.git Split policy into writing- and policy. --- diff --git a/Documentation/user/GNUmakefile b/Documentation/user/GNUmakefile index 59cf7a11af..dfa4342c9e 100644 --- a/Documentation/user/GNUmakefile +++ b/Documentation/user/GNUmakefile @@ -3,7 +3,8 @@ depth=../.. LATEX_FILES =$(call src-wildcard,*.latex) -EXTRA_DIST_FILES= $(LATEX_FILES) $(IMAGES) README.txt $(EPS_ILLUSTRATIONS) +EXTRA_DIST_FILES = $(LATEX_FILES) $(IMAGES) $(EPS_ILLUSTRATIONS) +EXTRA_DIST_FILES += README.txt writing-texinfo.txt policy.txt IMAGES=$(call src-wildcard,*.png) EPS_ILLUSTRATIONS=context-example.eps diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index 80c9f92c16..e38d7e86c5 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -3,7 +3,8 @@ Info for Documentation %%%%% GENERAL POLICY -See policy.txt +Formatting: writing-texinfo.txt +General policy: policy.txt %%%%% UPDATING DOCS diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt index d3661ab39a..d24d285e3f 100644 --- a/Documentation/user/policy.txt +++ b/Documentation/user/policy.txt @@ -76,7 +76,7 @@ main docs Application Usage: @rprogram{blah}. - Installed files: @file{blahz}. + Installed files: @file{path/to/dir/blahz}. Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}. (if there is only one entry, omit a final period. If there @@ -90,179 +90,13 @@ main docs * To create links, use @ref{} if the link is within the same manual. -* @commonprop and @refbugs are optional. - * Do not include any real info in second-level sections (ie 1.1 Pitches). A first-level section may have introductory material, but other than that all material goes into third-level sections (ie 1.1.1 Writing Pitches). -%%%%% LILYPOND FORMATTING - -* Use two spaces for indentation in lilypond examples. (no tabs) - -* If possible, only write one bar per line. The notes on each - line should be an independent line. - Bad: - \override textscript #'padding = #3 c1^"hi" - Good: - \override textscript #'padding = #3 - c1^"hi" - -* LilyPond input should be produce via - @lilypond[verbatim,quote,ragged-right] - with `fragment' and `relative=2' optional. - - Examples about page layout may alter the quote/ragged-right - options. Omitting `verbatim' is not allowed. - -* Inspirational headwords are produced with - @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] - {pitches-headword.ly} - -* Avoid long stretches of input code. Noone is going to read them - in print. Instead refer to an example input file with @lsr{}. - -* If you want to work on an example outside of the manual (for - easier/faster processing), use this header: - -\paper { - #(define dump-extents #t) - indent = 0\mm - line-width = 160\mm - 2.0 * 0.4\in - ragged-right = ##t - force-assignment = #"" - line-width = #(- line-width (* mm 3.000000)) -} - -\layout { -} - - You may not change any of these values. If you are making an - example demonstrating special \paper{} values, contact the - Documentation Editor. - - -%%%%% TEXT FORMATTING - -* Lines should be less than 72 characters long. (I personally - recommend writing with 66-char lines, but don't bother modifying - existing material.) - -* Do not use tabs. They expand to nothing in DVI output. - -* Do not use spaces at the beginning of a line (except in @example - or @verbatim environments), and do not use more than a single - space between words. `makeinfo' copies the input lines verbatim - without removing those spaces. - -* Use two spaces after a period. - -* Variables or numbers which consist of a single character - (probably followed by a punctuation mark) should be tied - properly, either to the previous or the next word. Example: - - The variable@tie{}@var{a} ... - -* To get consistent indentation in the DVI output it is better to - avoid the @verbatim environment. Use the @example environment - instead if possible, but without extraneous indentation. For - example, this - - @example - foo { - bar - } - @end example - - should be replaced with - - @example - foo { - bar - } - @end example - - where `@example' starts the line (without leading spaces). - -* Do not compress the input vertically; this is, do not use - - Beginning of logical unit - @example - ... - @end example - continuation of logical unit - - but - - Beginning of logical unit - - @example - ... - @end example - - @noindent - continuation of logical unit - - This makes it easier to avoid forgetting the `@noindent'. Only - use @noindent if the material is discussing the same material; - new material should simply begin without anything special on the - line above it. - -* in @itemize use @item on a separate line like this: - @itemize - @item - Foo - - @item - Bar - - Do not use @itemize @bullet. - -* Specially-marked text: - - @code{}: actual lilypond code or property/context names. - - - ** Any `\' used inside the commands below must be ** - ** written as `\\'. Even if they are inside a @code{}. ** - ( this should only affect @warning{} ) - - @notation{}: refers to pieces of notation, such as - "@notation{crescendo} is often abbreviated as - @notation{cresc.}" This should also be used to refer to - specific lyrics ("the @notation{A - men} is centered...") - @q{}: used for `vague' terms in English (and other natural - languages). - @qq{}: only for actual quotes -- i.e. "he said" or "she - wrote". - @warning{}: produces a "Note: " box. Use for important - messages. - -* References must occur at the end of a sentence, for more - information see @ref{the texinfo manual}. Ideally this should - also be the final sentence of a paragraph, but this is not - required. Any link in a doc section must be duplicated in the - @seealso section at the bottom. - -* Introducing examples may be done with - . (ie finish the previous sentence/paragaph) - : (ie `in this example:') - , (ie `may add foo with the blah construct,') - - -%%%%% READABILITY - -* Non-ASCII characters which are in utf-8 should be directly used; - this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that - all such characters appear in all output formats. - -* Don't use a @ref{link to another section} in the middle of a - sentence. It looks ok in HTML, moderately bad in PDF, and - utterly horrible in INFO. Instead, reword the sentence so that - users are encouraged to see @ref{link to another section}. - (at the end of the sentence) +%%%%% GENERAL WRITING * Do not forget to create @cindex entries for new sections of text. Enter commands with @funindex, i.e. @@ -273,14 +107,11 @@ main docs Both index commands should go in front of the actual material. -* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. - -* Colon usage - - 1. To introduce lists - 2. When beginning a quote: "So, he said,..." - This usage is rarer. Americans often just use a comma. - 3. When adding a defining example at the end of a sentence. +* Preferred terms: + - in general, use the American spellings. The internal + lilypond property names use this spelling. + - list of specific terms: +canceled, %%%%% TECHNICAL WRITING STYLE @@ -306,9 +137,4 @@ main docs Say `invalid' instead. -FOR DOC EDITOR ONLY - -* sectioning commands (@node and @section) must not appear inside - an @ignore. Separate those commands with a space, ie @n ode. - diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt new file mode 100644 index 0000000000..90230cf02a --- /dev/null +++ b/Documentation/user/writing-texinfo.txt @@ -0,0 +1,220 @@ +DOCUMENTATION FORMATTING +------------------------ + +The language is called texinfo; you can see its manual here: +http://www.gnu.org/software/texinfo/manual/texinfo/ + +However, you don't need to read those docs. The most important +thing to notice is that text is text. If you see a mistake in the +text, you can fix it. If you want to change the order of +something, you can cut-and-paste that stuff into a new location. + + +%%%%% SECTIONING COMMANDS + +Most of the manual operates at the + @node Foo + @unnumberedsubsubsec Foo +level. Sections are created with + @node Foo + @subsection Foo +commands. + +* sectioning commands (@node and @section) must not appear inside + an @ignore. Separate those commands with a space, ie @n ode. + + + +%%%%% LILYPOND FORMATTING + +* Use two spaces for indentation in lilypond examples. (no tabs) + +* If possible, only write one bar per line. The notes on each + line should be an independent line. + Bad: + \override textscript #'padding = #3 c1^"hi" + Good: + \override textscript #'padding = #3 + c1^"hi" + +* LilyPond input should be produce via + @lilypond[verbatim,quote,ragged-right] + with `fragment' and `relative=2' optional. + + Examples about page layout may alter the quote/ragged-right + options. Omitting `verbatim' is not allowed except for special + circumstances. + +* Inspirational headwords are produced with + @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] + {pitches-headword.ly} + +* Avoid long stretches of input code. Noone is going to read them + in print. Please create a smaller example. (the smaller + example does not need to be minimal, however) + +* If you want to work on an example outside of the manual (for + easier/faster processing), use this header: + +\paper { + #(define dump-extents #t) + indent = 0\mm + line-width = 160\mm - 2.0 * 0.4\in + ragged-right = ##t + force-assignment = #"" + line-width = #(- line-width (* mm 3.000000)) +} + +\layout { +} + + You may not change any of these values. If you are making an + example demonstrating special \paper{} values, contact the + Documentation Editor. + + +%%%%% TEXT FORMATTING + +* Lines should be less than 72 characters long. (I personally + recommend writing with 66-char lines, but don't bother modifying + existing material.) + +* Do not use tabs. + +* Do not use spaces at the beginning of a line (except in @example + or @verbatim environments), and do not use more than a single + space between words. `makeinfo' copies the input lines verbatim + without removing those spaces. + +* Use two spaces after a period. + +* Variables or numbers which consist of a single character + (probably followed by a punctuation mark) should be tied + properly, either to the previous or the next word. Example: + + The variable@tie{}@var{a} ... + +* To get consistent indentation in the DVI output it is better to + avoid the @verbatim environment. Use the @example environment + instead if possible, but without extraneous indentation. For + example, this + + @example + foo { + bar + } + @end example + + should be replaced with + + @example + foo { + bar + } + @end example + + where `@example' starts the line (without leading spaces). + +* Do not compress the input vertically; this is, do not use + + Beginning of logical unit + @example + ... + @end example + continuation of logical unit + + but + + Beginning of logical unit + + @example + ... + @end example + + @noindent + continuation of logical unit + + This makes it easier to avoid forgetting the `@noindent'. Only + use @noindent if the material is discussing the same material; + new material should simply begin without anything special on the + line above it. + +* in @itemize use @item on a separate line like this: + @itemize + @item + Foo + + @item + Bar + + Do not use @itemize @bullet. + + +%%%%% SYNTAX SURVEY + +@c - single line comments +@ignore ... @end ignore - multi-line comment + +@cindex - General index. Please add as many as you can. +@funindex - is for a \lilycommand. + +@example ... @end ignore - example text that should be set as a + blockquote. Any {} must be escaped with @{ }@ +@itemize @item A @item B ... @end itemize - for bulleted lists. + Do not compress vertically like this. + +@code{} - typeset in a tt-font. Use for actual lilypond code or + property/context names. +@notation{} - refers to pieces of notation, e.g. + "@notation{cres.}". Also use to specific lyrics ("the + @notation{A - men} is centered") +@q{} - Single quotes. Used for `vague' terms. +@qq{} - Double quotes. Used for actual quotes ("he said"). + +@warning{}: produces a "Note: " box. Use for important + messages. + +@tie{} - Variables or numbers which consist of a single character + (probably followed by a punctuation mark) should be tied + properly, either to the previous or the next word. Example: + "The letter@tie{}@q{I} is skipped" + +@var - Use for variables. +@warning{} - produces a "Note: " box. + Any `\' used inside this must be written as `\\'. + + + +%%%%% OTHER TEXT CONCERNS + +* References must occur at the end of a sentence, for more + information see @ref{the texinfo manual}. Ideally this should + also be the final sentence of a paragraph, but this is not + required. Any link in a doc section must be duplicated in the + @seealso section at the bottom. + +* Introducing examples may be done with + . (ie finish the previous sentence/paragaph) + : (ie `in this example:') + , (ie `may add foo with the blah construct,') + +* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. + +* Colon usage + + 1. To introduce lists + 2. When beginning a quote: "So, he said,..." + This usage is rarer. Americans often just use a comma. + 3. When adding a defining example at the end of a sentence. + +* Non-ASCII characters which are in utf-8 should be directly used; + this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that + all such characters appear in all output formats. + +* Don't use a @ref{link to another section} in the middle of a + sentence. It looks ok in HTML, moderately bad in PDF, and + utterly horrible in INFO. Instead, reword the sentence so that + users are encouraged to see @ref{link to another section}. + (at the end of the sentence) + +