From 101210f95c0bc5c790c3051d35af60a045abacc2 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Sun, 7 Jun 2009 11:49:59 -0700 Subject: [PATCH] Doc: Remove unneeded doc files (merged with CG). (cherry picked from commit 13252b9608ada70804931302d6023fb661ddf4d4) --- Documentation/user/README.txt | 12 +- Documentation/user/policy.txt | 215 ------------------ Documentation/user/writing-sections.txt | 106 --------- Documentation/user/writing-texinfo.txt | 280 ------------------------ 4 files changed, 1 insertion(+), 612 deletions(-) delete mode 100644 Documentation/user/policy.txt delete mode 100644 Documentation/user/writing-sections.txt delete mode 100644 Documentation/user/writing-texinfo.txt diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index cb344d3afa..45058ea3ac 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -1,15 +1,5 @@ Info for Documentation ---------------------- -%%%%% GENERAL POLICY +See CG 3. Documentation work -Formatting: writing-texinfo.txt -General policy: policy.txt - - -%%%%% UPDATING DOCS -cd into Documentation and run - -find . -name '*.itely' | xargs convert-ly -e - -(This also updates translated docs.) diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt deleted file mode 100644 index 0460e7ad3b..0000000000 --- a/Documentation/user/policy.txt +++ /dev/null @@ -1,215 +0,0 @@ -DOCUMENTATION POLICY --------------------- - - -%%%%% 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. - - -%%%%% 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. - -* 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). - - -%%%%% 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/. - - -%%%%% 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, ie - @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 -simultaenous 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 <>) - - -%%%%% TECHNICAL WRITING 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), say `@command{lilypond}'. - -* Do not explicitly refer to the reader/user. There is no one - else besides the reader and the writer. - -* Do not use abbreviations (don't, won't, etc.). If you do, use a - comma after it: - - blabla blabla, i.e., blabla blabla - -* Avoid fluff (``Notice that,'' ``as you can see,'' - ``Currently,''). - -* The use of the word `illegal' is inappropriate in most cases. - Say `invalid' instead. - - - diff --git a/Documentation/user/writing-sections.txt b/Documentation/user/writing-sections.txt deleted file mode 100644 index 54cd534634..0000000000 --- a/Documentation/user/writing-sections.txt +++ /dev/null @@ -1,106 +0,0 @@ -CHECKLIST FOR DOC SECTION REWRITES - -You've volunteered (or are considering volunteering) to edit a -section of the NR. Congratulations! You'll learn a lot about -this part of lilypond. You'll also get thoroughly fed up with -documentation work, and especially with me... but as they say, -"you can't make an omelett without breaking a few eggs". Welcome -to egg-hood! - -REQUIRED READING - -- policy.txt -- writing-texinfo.txt -- this document :) -- NR 1.1 Pitches. Ideally, read it in your favorite output format - (either info, PDF, or HTML), *and* in source format - (pitches.itely). This is our "demonstration" chapter, so the - below points really just boil down to "make it like - pitches.itely". - - -WORKING - -I recommend working on one subsection at a time. For each -subsection, -- check the mundane formatting. Are the headings (@predefined, - @seealso, etc) in the right order? -- add any appropriate index entries. -- check the links in the @seealso section -- links to music - glossary, internal references, and other NR sections are the - main concern. Check for potential additions. -- move LSR-worthy material into LSR. Add the snippet (or - just send it to Valentin for adding), delete the material from - the .itely file, and add a @lilypondfile command. - -- check the examples and descriptions. Do they still work? - *Do not* assume that the existing text is accurate/complete; - some of the manual is highly out of date. -- is the material in the @knownissues still accurate? -- process anything on the TODO list on the GDP web site. -- can the examples be improved (made more explanatory), or is - there any missing info? (feel free to ask specific questions - on -user; a couple of people claimed to be interesting in being - "consultants" who would help with such questions) - -In general, I favor short text explanations with good examples -- -"an example is worth a thousand words". When I worked on the -docs, I spent about half my time just working on those tiny -lilypond examples. Making easily-understandable examples is much -harder than it looks. - - -TWEAKS - -In general, any \set or \override commands should go in the -"select snippets" section, which means that they should go in LSR -and not the .itely file. For some cases, the command obviously -belongs in the "main text" (ie not inside @predefined or @seealso -or whatever) -- instrument names are a good example of this. - \set Staff.instrumentName = #"foo" -On the other side of this, - \override Score.Hairpin #'after-line-breaking = ##t -clearly belongs in LSR. - -I'm quite willing to discuss specific cases if you think that a -tweaks needs to be in the main text. But items that can go into -LSR are easier to maintain, so I'd like to move as much as -possible into there. - - -It would be "nice" if you spent a lot of time crafting nice tweaks -for users... but my recommendation is *not* to do this. There's a -lot of doc work to do without adding examples of tweaks. Tweak -examples are trivial to add later -- they could be made by normal -users, or by you after GDP is over. - -Basically, it's not something that needs to be done while I'm -around. Remember that I'm gone in August at the latest; there's a -*lot* of doc work that should be done before then. I strongly -recommend that you save all the tweaks until later. - - -FINAL - -- when you think you're finished, let me know. I'll spend a few - minutes and send you a list of mistakes to fix. - (there's a *lot* of details to cover; we'll probably spend a - week going back and forth like this. See earlier warning about - hating me by the time you're done with a doc section :) -- I'll ask people on -user to review the Snippet list at this - time; correcting things on the Snippet list is much easier than - getting comments on the integrated snippets. -- when we're both satisfied with the section, we'll invite - comments from -user. Judging from my experience with Pitches, - it will take between three and five weeks to keep on revising - the "final" version. - -I personally found it quite frustrating to still be fixing -problems in a doc section which I thought was "perfect" a whole -bloody *month* ago. Don't get me wrong; it's great that we get so -many comments from -user. :) But just be aware that when you -think you're finally done with a section, you're actually only -halfway there. - - - diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt deleted file mode 100644 index 8b55e9ab79..0000000000 --- a/Documentation/user/writing-texinfo.txt +++ /dev/null @@ -1,280 +0,0 @@ -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 - @subsubsection Foo -level. Sections are created with - @node Foo - @subsection Foo -commands. - -* Please leave two blank lines above a @node; this makes it easier - to find sections in texinfo. - -* 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) - -* 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" - -* All engravers should have double-quotes around them: - \consists "Spans_arpeggio_engraver" - Again, LilyPond does not strictly require this, but it is a - useful standard to follow. - -* Examples should end with a complete bar if possible. - -* 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" - -* Most LilyPond input should be produced with: - @lilypond[verbatim,quote,relative=2] - or - @lilypond[verbatim,quote,relative=1] - - If you want to use \layout{} or define variables, use - @lilypond[verbatim,quote] - - In rare cases, other options may be used (or omitted), but ask first. - -* Inspirational headwords are produced with - @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] - {pitches-headword.ly} - -* LSR snippets are linked with - @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] - {filename.ly} - excepted in Templates, where `doctitle' may be omitted. - -* 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) - -* Specify durations for at least the first note of every bar. - -* If possible, end with a complete bar. - -* Comments should go on their own line, and be placed before the - line(s) to which they refer. - -* Add extra spaces around { } marks; ie - not: \chordmode {c e g} - but instead: \chordmode { c e g } - -* 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. - -* 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. - -* In examples of syntax, use @var{musicexpr} for a music - expression. - -* 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. - -* 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. - -* 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, - enclose it with - - @w{ ... } - - e.g. - - @w{"@version{}"} - - to prevent an ugly line break in PDF output. - - -%%%%% SYNTAX SURVEY - -@c - single line comments - "@c NOTE:" is a comment which should remain in the final - version. (gp only command ;) -@ignore ... @end ignore - multi-line comment - -@cindex - General index. Please add as many as you can. Don't - capitalize the first word. -@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. If the name contains a space, wrap - the entire thing inside @w{@code{ }}. -@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. -@q{} - Single quotes. Used for `vague' terms. -@qq{} - Double quotes. Used for actual quotes ("he said") or for - introducing special input modes. - -@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. Use for important messages. - -@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). - - - -%%%%% 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 must be done with - . (ie finish the previous sentence/paragaph) - : (ie `in this example:') - , (ie `may add foo with the blah construct,') - The old "sentence runs directly into the example" method is not - allowed any more. - -* 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. - -- 2.39.2