From 862fc864d7ec46659e26c5ac27d8a247ae3e625b Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Mon, 12 Jan 2009 21:57:41 +0800 Subject: [PATCH] Halfway do Doc stuff. --- Documentation/devel/doc-work.itexi | 256 +++++++++++++++++++++-------- 1 file changed, 191 insertions(+), 65 deletions(-) diff --git a/Documentation/devel/doc-work.itexi b/Documentation/devel/doc-work.itexi index c3d264f124..55bac1d26b 100644 --- a/Documentation/devel/doc-work.itexi +++ b/Documentation/devel/doc-work.itexi @@ -15,16 +15,15 @@ @node Introduction to documentation work @section Introduction to documentation work -Our documentation tries to adhere to the @ref{Documentation -policy} as strictly as possible. One policy in particular is -often questioned by potential contributors: we do not repeat -material in the Notation Reference, and instead provide links to -the @qq{definitive} presentation of that information. - -Some people point out, with good reason, that this makes the -documentation harder to read. If we repeated certain information -in relevant places, readers would be less likely to miss that -information. +Our documentation tries to adhere to our @ref{Documentation +policy}. This policy contains a few items which may seem odd. +One policy in particular is often questioned by potential +contributors: we do not repeat material in the Notation Reference, +and instead provide links to the @qq{definitive} presentation of +that information. Some people point out, with good reason, that +this makes the documentation harder to read. If we repeated +certain information in relevant places, readers would be less +likely to miss that information. That reasoning is sound, but we have two counter-arguments. First, the Notation Reference -- one of @emph{five} manuals for @@ -72,87 +71,135 @@ to do anything fancy, discuss it on @code{lilypond-devel} first.} @subsection Sectioning commands Most of the manual operates at the + +@example @@node Foo @@subsubsection Foo +@end example + +@noindent level. Sections are created with + +@example @@node Foo @@subsection Foo -commands. +@end example + +@itemize +@item Please leave two blank lines above a @@node; this makes it +easier to find sections in texinfo. -* Please leave two blank lines above a @@node; this makes it easier - to findw sections in texinfo. +@item Sectioning commands (@@node and @@section) must not appear +inside an @@ignore. Separate those commands with a space, ie @@n +ode. -* sectioning commands (@@node and @@section) must not appear inside - an @@ignore. Separate those commands with a space, ie @@n ode. +@end itemize @subsection LilyPond formatting -* Use two spaces for indentation in lilypond examples. (no tabs) +@itemize + +@item Use two spaces for indentation in lilypond examples. (no +tabs) + +@item All text strings should be prefaced with #. LilyPond does +not strictly require this, but it is helpful to get users +accustomed to this scheme construct. ie @code{\set +Staff.instrumentName = #"cello"} -* All text strings should be prefaced with #. LilyPond does not - strictly require this, but it is helpful to get users accustomed - to this scheme construct. ie - \set Staff.instrumentName = #"cello" +@item All engravers should have double-quotes around them: -* All engravers should have double-quotes around them: +@example \consists "Spans_arpeggio_engraver" - Again, LilyPond does not strictly require this, but it is a - useful standard to follow. +@end example -* Examples should end with a complete bar if possible. +Again, LilyPond does not strictly require this, but it is a useful +standard to follow. -* If possible, only write one bar per line. The notes on each - line should be an independent line -- tweaks should occur on - their own line if possible. - Bad: - \override textscript #'padding = #3 c1^"hi" - Good: - \override textscript #'padding = #3 - c1^"hi" +@item Examples should end with a complete bar if possible. -* Most LilyPond input should be produced with: - @@lilypond[verbatim,quote,relative=2] - or - @@lilypond[verbatim,quote,relative=1] +@item If possible, only write one bar per line. The notes on each +line should be an independent line -- tweaks should occur on their +own line if possible. Bad: - If you want to use \layout@{@} or define variables, use - @@lilypond[verbatim,quote] +@example +\override textscript #'padding = #3 c1^"hi" +@end example - In rare cases, other options may be used (or omitted), but ask first. +Good: -* Inspirational headwords are produced with - @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] - @{pitches-headword.ly@} +@example +\override textscript #'padding = #3 +c1^"hi" +@end example -* LSR snippets are linked with - @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] - @{filename.ly@} - excepted in Templates, where `doctitle' may be omitted. +@item Most LilyPond input should be produced with: -* 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) +@example +@@lilypond[verbatim,quote,relative=2] +@end example -* Specify durations for at least the first note of every bar. +@noindent +or -* If possible, end with a complete bar. +@example +@@lilypond[verbatim,quote,relative=1] +@end example -* Comments should go on their own line, and be placed before the - line(s) to which they refer. +If you want to use \layout@{@} or define variables, use -* Add extra spaces around @{ @} marks; ie - not: \chordmode @{c e g@} - but instead: \chordmode @{ c e g @} +@example +@@lilypond[verbatim,quote] +@end example + +In rare cases, other options may be used (or omitted), but ask first. -* If you only have one bar per line, omit bar checks. If you - put more than one bar per line (not recommended), then include - bar checks. +@item +Inspirational headwords are produced with -* If you want to work on an example outside of the manual (for - easier/faster processing), use this header: +@example +@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] +@{pitches-headword.ly@} +@end example +@item LSR snippets are linked with + +@example +@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +@{filename.ly@} +@end example + +@noindent +excepted in Templates, where `doctitle' may be omitted. + +@item 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) + +@item Specify durations for at least the first note of every bar. + +@item If possible, end with a complete bar. + +@item Comments should go on their own line, and be placed before +the line(s) to which they refer. + +@item Add extra spaces around @{ @} marks; ie + +@example +not: \chordmode @{c e g@} +but instead: \chordmode @{ c e g @} +@end example + +@item If you only have one bar per line, omit bar checks. If you +put more than one bar per line (not recommended), then include bar +checks. + +@item If you want to work on an example outside of the manual (for +easier/faster processing), use this header: + +@example \paper @{ #(define dump-extents #t) indent = 0\mm @@ -164,41 +211,54 @@ commands. \layout @{ @} +@end example - You may not change any of these values. If you are making an - example demonstrating special \paper@{@} values, contact the - Documentation Editor. +You may not change any of these values. If you are making an +example demonstrating special \paper@{@} values, contact the +Documentation Editor. + +@end itemize @subsection Text formatting +@itemize + +@item * Lines should be less than 72 characters long. (I personally recommend writing with 66-char lines, but don't bother modifying existing material.) +@item * Do not use tabs. +@item * 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. +@item * Use two spaces after a period. +@item * In examples of syntax, use @@var@{musicexpr@} for a music expression. +@item * Don't use @@rinternals@{@} in the main text. If you're tempted to do so, you're probably getting too close to "talking through the code". If you really want to refer to a context, use @@code@{@} in the main text and @@rinternals@{@} in the @@seealso. +@item * 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@} ... +@item * 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 @@ -220,6 +280,7 @@ commands. where `@@example' starts the line (without leading spaces). +@item * Do not compress the input vertically; this is, do not use Beginning of logical unit @@ -244,6 +305,7 @@ commands. new material should simply begin without anything special on the line above it. +@item * in @@itemize use @@item on a separate line like this: @@itemize @@item @@ -254,6 +316,7 @@ commands. Do not use @@itemize @@bullet. +@item * To get LilyPond version, use @@version@{@} (this does not work inside LilyPond snippets). If you write "@@version@{@}" (enclosed with quotes), or generally if @@version@{@} is not followed by a space, @@ -266,57 +329,79 @@ commands. @@w@{"@@version@{@}"@} to prevent an ugly line break in PDF output. +@end itemize @subsection Syntax survey +@itemize +@item @@c - single line comments "@@c NOTE:" is a comment which should remain in the final version. (gp only command ;) +@item @@ignore ... @@end ignore - multi-line comment +@item @@cindex - General index. Please add as many as you can. Don't capitalize the first word. +@item @@funindex - is for a \lilycommand. +@item @@example ... @@end ignore - example text that should be set as a blockquote. Any @{@} must be escaped with @@@{ @}@@ +@item @@itemize @@item A @@item B ... @@end itemize - for bulleted lists. Do not compress vertically like this. +@item @@code@{@} - typeset in a tt-font. Use for actual lilypond code or property/context names. If the name contains a space, wrap the entire thing inside @@w@{@@code@{ @}@}. +@item @@notation@{@} - refers to pieces of notation, e.g. "@@notation@{cres.@}". Also use to specific lyrics ("the @@notation@{A - men@} is centered"). Only use once per subsection per term. +@item @@q@{@} - Single quotes. Used for `vague' terms. +@item @@qq@{@} - Double quotes. Used for actual quotes ("he said") or for introducing special input modes. +@item @@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" +@item @@var - Use for variables. +@item @@warning@{@} - produces a "Note: " box. Use for important messages. +@item @@bs - Generates a backslash inside @@warning. Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}' (texinfo would also allow \\, but this breaks with PDF output). +@end itemize + @subsection Other text concerns +@itemize + +@item * 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. +@item * Introducing examples must be done with . (ie finish the previous sentence/paragaph) : (ie `in this example:') @@ -324,8 +409,10 @@ commands. The old "sentence runs directly into the example" method is not allowed any more. +@item * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. +@item * Colon usage 1. To introduce lists @@ -333,10 +420,13 @@ commands. This usage is rarer. Americans often just use a comma. 3. When adding a defining example at the end of a sentence. +@item * 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. +@end itemize + @@ -350,6 +440,9 @@ There are four parts to the documentation: the Learning Manual, the Notation Reference, the Program Reference, and the Music Glossary. +@itemize + +@item * Learning Manual: The LM is written in a tutorial style which introduces the most important concepts, structure and syntax of the elements of a @@ -371,6 +464,7 @@ Users are encouraged to read the complete Learning Manual from start-to-finish. +@item * Notation Reference: a (hopefully complete) description of LilyPond input notation. Some material from here may be duplicated in the Learning Manual (for teaching), but consider @@ -399,6 +493,7 @@ Finally, you should assume that users know what the notation means; explaining musical concepts happens in the Music Glossary. +@item * Application Usage: information about using the program lilypond with other programs (lilypond-book, operating systems, GUIs, convert-ly, etc). This section is written in formal technical @@ -407,27 +502,37 @@ means; explaining musical concepts happens in the Music Glossary. Users are not expected to read this manual from start to finish. +@item * Music Glossary: information about the music notation itself. Explanations and translations about notation terms go here. Users are not expected to read this manual from start to finish. +@item * Internals Reference: not really a documentation book, since it is automagically generated from the source, but this is its name. +@end itemize + @subsection Section organization -The order of headings inside documentation sections should be: +@itemize + +@item The order of headings inside documentation sections should +be: +@example main docs @@predefined @@endpredefined @@snippets @@seealso @@knownissues +@end example +@item * You _must_ include a @@seealso. The order of items inside the @@seealso section is @@ -472,17 +577,22 @@ main docs Don't insert an empty line between @@seealso and the first entry! Otherwise there is excessive vertical space in the PDF output. +@item * To create links, use @@ref@{@} if the link is within the same manual. +@item * @@predefined ... @@endpredefined is for commands in ly/*-init.ly FIXME? +@item * 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). +@end itemize + @subsection Checking cross-references @@ -500,6 +610,9 @@ scm/ and lily/. @subsection General writing +@itemize + +@item * Do not forget to create @@cindex entries for new sections of text. Enter commands with @@funindex, i.e. @@cindex pitches, writing in different octaves @@ -519,6 +632,7 @@ scm/ and lily/. and NOT @@funindex #(set-accidental-style modern-voice-cautionary) +@item * Preferred terms: - in general, use the American spellings. The internal lilypond property names use this spelling. @@ -530,29 +644,41 @@ bar line: the symbol delimiting a measure NOT barline note head NOT notehead chord construct NOT chord (when referring to <>) +@end itemize + @subsection Technical writing style +@itemize + +@item * Do not refer to LilyPond in the text. The reader knows what the manual is about. If you do, capitalization is LilyPond. +@item * If you explicitly refer to `lilypond' the program (or any other command to be executed), say `@@command@{lilypond@}'. +@item * Do not explicitly refer to the reader/user. There is no one else besides the reader and the writer. +@item * Do not use abbreviations (don't, won't, etc.). If you do, use a comma after it: blabla blabla, i.e., blabla blabla +@item * Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,''). +@item * The use of the word `illegal' is inappropriate in most cases. Say `invalid' instead. +@end itemize + @node Tips for writing docs @section Tips for writing docs -- 2.39.2