[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Documentation work ] | [ > ] |
3.3 Documentation policy
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Documentation policy ] | [ Up : Documentation policy ] | [ > ] |
3.3.1 Books
There are four parts to the documentation: the Learning Manual, the Notation Reference, the Program Reference, and the Music Glossary.
-
Learning Manual:
The LM is written in a tutorial style which introduces the most important concepts, structure and syntax of the elements of a LilyPond score in a carefully graded sequence of steps. Explanations of all musical concepts used in the Manual can be found in the Music Glossary, and readers are assumed to have no prior knowledge of LilyPond. The objective is to take readers to a level where the Notation Reference can be understood and employed to both adapt the templates in the Appendix to their needs and to begin to construct their own scores. Commonly used tweaks are introduced and explained. Examples are provided throughout which, while being focussed on the topic being introduced, are long enough to seem real in order to retain the readers’ interest. Each example builds on the previous material, and comments are used liberally. Every new aspect is thoroughly explained before it is used.
Users are encouraged to read the complete Learning Manual from start-to-finish.
-
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 the NR to be the
"definitive" description of each notation element, with the LM
being an "extra". The goal is _not_ to provide a step-by-step
learning environment – do not avoid using notation that has not
be introduced previously in the NR (for example, use \break if
appropriate). This section is written in formal technical writing
style.
Avoid duplication. Although users are not expected to read this manual from start to finish, they should be familiar with the material in the Learning Manual (particularly “Fundamental Concepts”), so do not repeat that material in each section of this book. Also watch out for common constructs, like ^ - _ for directions – those are explained in NR 3. In NR 1, you can write: DYNAMICS may be manually placed above or below the staff, see @ref{Controlling direction and placement}.
Most tweaks should be added to LSR and not placed directly in the .itely file. In some cases, tweaks may be placed in the main text, but ask about this first.
Finally, you should assume that users know what the notation means; explaining musical concepts happens in the Music Glossary.
-
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
writing style.
Users are not expected to read this manual from start to finish.
-
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.
- Internals Reference: not really a documentation book, since it is automagically generated from the source, but this is its name.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Documentation policy ] | [ > ] |
3.3.2 Section organization
-
The order of headings inside documentation sections should
be:
main docs @predefined @endpredefined @snippets @seealso @knownissues
-
You must include a @seealso.
-
The order of items inside the @seealso section is
Music Glossary: @rglos{foo}, @rglos{bar}. Learning Manual: @rlearning{baz}, @rlearning{foozle}. Notation Reference: @ruser{faazle}, @ruser{boo}. Application Usage: @rprogram{blah}. Installed Files: @file{path/to/dir/blahz}. Snippets: @rlsr{section}. Internals Reference: @rinternals{fazzle}, @rinternals{booar}.
- If there are multiple entries, separate them by commas but do not include an ‘and’.
- Always end with a period.
-
Place each link on a new line as above; this makes it much easier
to add or remove links. In the output, they appear on a single
line.
("Snippets" is REQUIRED; the others are optional)
- Any new concepts or links which require an explanation should go as a full sentence(s) in the main text.
- Don’t insert an empty line between @seealso and the first entry! Otherwise there is excessive vertical space in the PDF output.
-
The order of items inside the @seealso section is
- To create links, use @ref{} if the link is within the same manual.
- @predefined ... @endpredefined is for commands in ly/*-init.ly FIXME?
- 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).
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Documentation policy ] | [ > ] |
3.3.3 Checking cross-references
Cross-references between different manuals are heavily used in the documentation, but they are not checked during compilation. However, if you compile the documentation, a script called check_texi_refs can help you with checking and fixing these cross-references; for information on usage, cd into a source tree where documentation has been built, cd into Documentation and look for check-xrefs and fix-xrefs targets in ’make help’ output. Note that you have to find yourself the source files to fix cross-references in the generated documentation such as the Internals Reference; e.g. you can grep scm/ and lily/.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Documentation policy ] | [ > ] |
3.3.4 General writing
-
Do not forget to create @cindex entries for new sections of text.
Enter commands with @funindex, i.e.
@cindex pitches, writing in different octaves @funindex \relative
do not bother with the @code{} (they are added automatically). These items are added to both the command index and the unified index.
Both index commands should go in front of the actual material.
@cindex entries should not be capitalized, ie
@cindex time signature
is preferred instead of “Time signature”, Only use capital letters for musical terms which demand them, like D.S. al Fine.
For scheme functions, only include the final part, i.e.,
@funindex modern-voice-cautionary and NOT @funindex #(set-accidental-style modern-voice-cautionary)
-
Preferred terms:
- In general, use the American spellings. The internal lilypond property names use this spelling.
-
List of specific terms:
canceled simultaneous NOT concurrent measure: the unit of music bar line: the symbol delimiting a measure NOT barline note head NOT notehead chord construct NOT chord (when referring to <>)
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Documentation policy ] | [ Tips for writing docs > ] |
3.3.5 Technical writing style
These refer to the NR. The LM uses a more gentle, colloquial style.
- Do not refer to LilyPond in the text. The reader knows what the manual is about. If you do, capitalization is LilyPond.
-
If you explicitly refer to ‘lilypond’ the program (or any other
command to be executed), write
@command{lilypond}
. - Do not explicitly refer to the reader/user. There is no one else besides the reader and the writer.
- Avoid contractions (don’t, won’t, etc.). Spell the words out completely.
- Avoid abbreviations, except for commonly used abbreviations of foreign language terms such as etc. and i.e.
- Avoid fluff (“Notice that,” “as you can see,” “Currently,”).
- The use of the word ‘illegal’ is inappropriate in most cases. Say ‘invalid’ instead.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Documentation policy ] | [ Tips for writing docs > ] |