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
%%%%% GENERAL POLICY
-See policy.txt
+Formatting: writing-texinfo.txt
+General policy: policy.txt
%%%%% UPDATING 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
* 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.
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
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.
-
--- /dev/null
+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)
+
+
projects / lilypond.git / commitdiff