Adding the following line to the docs will prevent hyphens
and underscores from line-breaking in the PDF output within
@code blocks and related commands:
@allowcodebreaks false
I've attached a patch that does this. Okay to push?
* * * * * * *
Also, I've reorganized the Texinfo usage policy and made a
number of additions to it. I've also attached a patch with
those changes. Okay to push?
Thanks
- Mark
From f4d747fa323a88d379de8d8bace8038bbcde1050 Mon Sep 17 00:00:00 2001
From: Mark Polesky <markpole...@yahoo.com>
Date: Thu, 25 Feb 2010 21:00:41 -0800
Subject: [PATCH 1/2] Doc: use `...@allowcodebreaks false' in manuals.
---
Documentation/changes.tely | 3 +--
Documentation/contributor.texi | 1 +
Documentation/essay.tely | 2 ++
Documentation/extending.tely | 1 +
Documentation/learning.tely | 1 +
Documentation/notation.tely | 1 +
Documentation/snippets.tely | 1 +
Documentation/usage.tely | 1 +
Documentation/web.texi | 1 +
9 files changed, 10 insertions(+), 2 deletions(-)
diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 50d8330..62e6259 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -41,8 +41,7 @@ This document is also available in @uref{changes.pdf,PDF}. It is part of
the @uref{lilypond/manuals.html,LilyPond Documentation}.
@end ifhtml
-
-
+...@allowcodebreaks false
@itemize @bullet
diff --git a/Documentation/contributor.texi b/Documentation/contributor.texi
index 25f96a2..188d055 100644
--- a/Documentation/contributor.texi
+++ b/Documentation/contributor.texi
@@ -70,6 +70,7 @@ Appendices
@contents
+...@allowcodebreaks false
@include contributor/introduction.itexi
@include contributor/source-code.itexi
diff --git a/Documentation/essay.tely b/Documentation/essay.tely
index 3db3294..25b8910 100644
--- a/Documentation/essay.tely
+++ b/Documentation/essay.tely
@@ -55,6 +55,8 @@ Copyright @copyright{} 2002--2010 by the authors.
@contents
+...@allowcodebreaks false
+
@include essay/engraving.itely
@include essay/literature.itely
diff --git a/Documentation/extending.tely b/Documentation/extending.tely
index 54f040c..2b3e7b2 100644
--- a/Documentation/extending.tely
+++ b/Documentation/extending.tely
@@ -60,6 +60,7 @@ Appendices
@contents
+...@allowcodebreaks false
@include extending/scheme-tutorial.itely
@include extending/programming-interface.itely
diff --git a/Documentation/learning.tely b/Documentation/learning.tely
index 9e052dc..2e4c15c 100644
--- a/Documentation/learning.tely
+++ b/Documentation/learning.tely
@@ -62,6 +62,7 @@ Appendices
@c TOC - tex
@contents
+...@allowcodebreaks false
@c INCLUDES
diff --git a/Documentation/notation.tely b/Documentation/notation.tely
index a2cc5f9..7d1d697 100644
--- a/Documentation/notation.tely
+++ b/Documentation/notation.tely
@@ -69,6 +69,7 @@ Appendices
@contents
+...@allowcodebreaks false
@include notation/notation.itely
@include notation/specialist.itely
diff --git a/Documentation/snippets.tely b/Documentation/snippets.tely
index 87412a2..258a358 100644
--- a/Documentation/snippets.tely
+++ b/Documentation/snippets.tely
@@ -96,6 +96,7 @@ Other collections
@contents
+...@allowcodebreaks false
@c Please take care of naming every .itely
@c with an existing tag name.
diff --git a/Documentation/usage.tely b/Documentation/usage.tely
index c7b6fb3..599d229 100644
--- a/Documentation/usage.tely
+++ b/Documentation/usage.tely
@@ -65,6 +65,7 @@ Appendices
@contents
+...@allowcodebreaks false
@include usage/running.itely
@include usage/updating.itely
diff --git a/Documentation/web.texi b/Documentation/web.texi
index 06c305b..f2001a8 100644
--- a/Documentation/web.texi
+++ b/Documentation/web.texi
@@ -160,6 +160,7 @@ Read more in our @ref{Introduction}!
@contents
+...@allowcodebreaks false
@c ****************** GENERAL STUFF FOR INFO ************
@ignore
--
1.6.3.3
From 1ae691e040d0647a47e976da60ae8b845a6451f8 Mon Sep 17 00:00:00 2001
From: Mark Polesky <markpole...@yahoo.com>
Date: Fri, 26 Feb 2010 15:55:15 -0800
Subject: [PATCH 2/2] Doc: CG: update/clarify Texinfo usage policy.
---
Documentation/contributor/doc-work.itexi | 400 ++++++++++++++++++------------
1 files changed, 235 insertions(+), 165 deletions(-)
diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 70bb1d7..2f6a7dc 100644
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -401,31 +401,11 @@ Documentation Editor.
@subsection Text formatting
@itemize
-
@item
Lines should be less than 72 characters long. (We personally
recommend writing with 66-char lines, but do not bother modifying
-existing material). However, see the note below regarding line
-lengths within @code{@@example} blocks.
-
-...@item
-Individual lines within an @code{@@example} block should not
-exceed 74 characters; otherwise they will run into the margin in
-the pdf output, and may get clipped. If an @code{@@example} block
-is part of an @code{@@item} within an @code{@@itemize} or
-...@code{@@enumerate} block, each line of the @code{@@example} should
-not exceed 70 columns---each additional level of @code{@@itemize}
-or @code{@@enumerate} shortens the line by about 4 columns.
-
-For command line examples, if possible, use a trailing backslash
-to break up a single line, indenting the next line with 2 spaces.
-If this isn't feasible, use @code{@@smallexample ...
-@@e...@tie{}smallexample} instead, which uses a smaller fontsize.
-Use @code{@@example} whenever possible, but if needed,
-...@code{@@smallexample} can fit up to 96 characters per line before
-running into the pdf margin. Each additional level of
-...@code{@@itemize} or @code{@@enumerate} shortens a
-...@code{@@smallexample} line by about 5 columns.
+existing material). Also see the recommendations for fixed-width
+fonts in the @ref{Syntax survey}.
@item
Do not use tabs.
@@ -449,232 +429,327 @@ tempted to do so, you're probably getting too close to @qq{talking
through the code}. If you really want to refer to a context, use
@code{@@c...@{@}} in the main text and @code{@@rintern...@{@}} in
the @code{@@seealso}.
+...@end itemize
-...@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:
-...@example
-The variable@@t...@{@}@@v...@{a@} ...
-...@end example
+...@node Syntax survey
+...@subsection Syntax survey
-...@item
-To get consistent indentation in the DVI output it is better to
-avoid the @code{@@verbatim} environment. Use the @code{@@example}
-environment instead if possible, but without extraneous
-indentation. For example, this
-...@example
-@@example
- foo @{
- bar
- @}
-@@end example
-...@end example
+...@menu
+* Comments::
+* Cross references::
+* External links::
+* Fixed-width font::
+* Indexing::
+* Lists::
+* Special characters::
+* Miscellany::
+...@end menu
-...@noindent
-should be replaced with
-...@example
-@@example
-foo @{
- bar
-...@}
-@@end example
-...@end example
+...@node Comments
+...@unnumberedsubsubsec Comments
-...@noindent
-where @q...@code{@@example}} starts the line (without leading
-spaces).
+...@itemize
+...@item
+...@code{@@c @dots{}} --- single line comment. @samp{@@c NOTE:} is a
+comment which should remain in the final version. (gp only
+command ;)
@item
-Do not compress the input vertically; that is, do not use
+...@code{@@ignore} --- multi-line comment:
@example
-Beginning of logical unit
-@@example
-...
-@@end example
-continuation of logical unit
+@@ignore
+...@dots{}
+@@end ignore
@end example
+...@end itemize
-...@noindent
-but instead do
-...@example
-Beginning of logical unit
+...@node Cross references
+...@unnumberedsubsubsec Cross references
-@@example
-...
-@@end example
+Enter the exact @code{@@node} name of the target reference between
+the brackets (e...@tie{}@w...@samp{@@r...@{syntax sur...@}}}).
-@@noindent
-continuation of logical unit
-...@end example
+...@itemize
+...@item
+...@code{@@r...@{@dot...@}} --- link within current manual.
-This makes it easier to remember the @q...@code{@@noindent}}. Only
-use @code{@@noindent} if the material is discussing the same
-material; new material should simply begin without anything
-special on the line above it.
+...@item
+...@code{@@rchan...@{@dot...@}} --- link to Changes.
@item
-in @code{@@itemize} and @code{@@enumerate} blocks, use
-...@code{@@item} on a separate line like this:
+...@code{@@rcont...@{@dot...@}} --- link to Contributor's Guide.
-...@example
-@@itemize
-@@item
-Foo
+...@item
+...@code{@@res...@{@dot...@}} --- link to Engraving Essay.
-@@item
-Bar
-...@end example
+...@item
+...@code{@@rext...@{@dot...@}} --- link to Extending LilyPond.
-Do not use @code{@@item...@tie{}@@bullet}.
+...@item
+...@code{@@rg...@{@dot...@}} --- link to the Music Glossary.
@item
-To get LilyPond version, use @code{@@vers...@{@}} (this does not
-work inside LilyPond snippets). If you write
-...@code{"@@vers...@{@}"} (enclosed with quotes), or generally if
-...@code{@@vers...@{@}} is not followed by a space, there will be an
-ugly line break in PDF output unless you enclose it with
+...@code{@@rintern...@{@dot...@}} --- link to the Internals Reference.
-...@example
-@@w...@{ ... @}
+...@item
+...@code{@@rlearn...@{@dot...@}} --- link to Learning Manual.
- e.g.
+...@item
+...@code{@@r...@{@dot...@}} --- link to a Snippet section.
-@@w...@{"@@vers...@{@}"@}
-...@end example
+...@item
+...@code{@@rprog...@{@dot...@}} --- link to Application Usage.
+...@item
+...@code{@@ru...@{@dot...@}} --- link to Notation Reference.
+
+...@item
+...@code{@@r...@{@dot...@}} --- link to General Informaion.
@end itemize
-...@node Syntax survey
-...@subsection Syntax survey
+...@node External links
+...@unnumberedsubsubsec External links
@itemize
@item
-...@code{@@bs} --- Generates a backslash inside @code{@@warning}.
-Any @q...@bs{}} used inside @code{@@warning} (and @code{@@q} or
-...@code{@@qq}) must be written as @q...@code{@@b...@{@}}} (texinfo would
-also allow @q...@bs{}@bs{}}, but this breaks with PDF output).
+...@code{@@em...@{@dot...@}} --- create a @code{mailto:} E-mail link.
@item
-...@code{@@c} --- single line comments. @q...@code{@@c NOTE:}} is a
-comment which should remain in the final version. (gp only
-command ;)
+...@code{@@u...@{@var{URL}[, @var{link tex...@}} --- link to an
+external url.
+...@end itemize
-...@item
-...@code{@@cindex} --- General index. Please add as many as you can.
-Don't capitalize the first word.
-...@item
-...@code{@@c...@{@}} --- 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 @code{@@w...@{@@c...@{ @}...@}}.
+...@node Fixed-width font
+...@unnumberedsubsubsec Fixed-width font
+...@itemize
@item
-...@code{@@example ... @@end example} --- example text that should be
-set as a blockquote. Any @co...@{@ti...@}} must be escaped with
-...@code{@@@{...@tie{}@@@}}.
+...@code{@@c...@{@dot...@}}, @code{@@s...@{@dot...@}} ---
+
+Use the @code{@@c...@{@dot...@}} command for individual
+language-specific tokens (keywords, commands, engravers, scheme
+symbols, etc.). Ideally, a single @code{@@c...@{@dot...@}} block
+should fit within one line in the PDF output. Use the
+...@code{@@s...@{@dot...@}} command when you have a short example of
+user input, unless it constitutes an entire @code{@@item} by
+itself, in which case @code{@@c...@{@dot...@}} is preferable.
+Otherwise, both should only be used when part of a larger sentence
+within a paragraph or @code{@@item}. Never use a
+...@code{@@c...@{@dot...@}} or @code{@@s...@{@dot...@}} block as a
+free-standing paragraph; use @code{@@example} instead.
+
+A single unindented line in the PDF has space for about 79
+fixed-width characters (76 if indented). Within an @code{@@item}
+there is space for about 75 fixed-width characters. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+However, even short blocks of @code{@@c...@{@dot...@}} and
+...@code{@@s...@{@dot...@}} can run into the margin if the Texinfo
+line-breaking algorithm gets confused. Additionally, blocks that
+are longer than this may in fact print nicely; it all depends
+where the line breaks end up. If you compile the docs yourself,
+check the PDF output to make sure the line breaks are
+satisfactory.
+
+The Texinfo setting @code{@@allowcodebreaks} is set to
+...@code{false} in the manuals, so lines within
+...@code{@@c...@{@dot...@}} or @code{@@s...@{@dot...@}} blocks will
+only break at spaces, not at hyphens or underscores. If the block
+contains spaces, use @code{@@w...@{@@c...@{@dot...@}@}} or
+...@code{@@w...@{@@s...@{@dot...@}@}} to prevent unexpected line breaks.
+
+...@item
+...@code{@@comm...@{@dot...@}} --- Use for command-line commands (eg.
+...@samp{@@comm...@{lilypond-book@}}).
+
+...@item
+...@code{@@example} --- Use for examples of program code. Do not add
+extraneous indentation (ie. don't start every line with
+whitespace). Use the following layout (notice the use of blank
+lines). Omit the @code{@@noindent} if the text following the
+example starts a new paragraph:
-...@item
-...@code{@@funindex} --- is for a \lilycommand.
+...@example
+...@var{@dots{}text leading into the exam...@dots{}}
-...@item
-...@code{@@ignore ... @@end ignore} --- multi-line comment
+@@example
+...@dots{}
+@@end example
-...@item
-...@code{@@itemize @@item A @@item B ... @@end itemize} --- for
-bulleted lists. Do not compress vertically like this.
+@@noindent
+...@var{continuation of the t...@dots{}}
+...@end example
-...@item
-...@code{@@notat...@{@}} --- refers to pieces of notation, e.g.
-...@qq{@code{@@notat...@{clef}.@}}. Also use for specific lyrics
-(@qq{the @code{@@notat...@{}a@tie...@tie{}men@} is centered}).
-Only use once per subsection per term.
+Individual lines within an @code{@@example} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@example} block
+is part of an @code{@@item}, individual lines in the
+...@code{@@example} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+For long command line examples, if possible, use a trailing
+backslash to break up a single line, indenting the next line with
+2 spaces. If this isn't feasible, use @samp{@@smallexample
+...@dots{} @@e...@tie{}smallexample} instead, which uses a smaller
+fontsize. Use @code{@@example} whenever possible, but if needed,
+...@code{@@smallexample} can fit up to 90 characters per line before
+running into the PDF margin. Each additional level of
+...@code{@@itemize} or @code{@@enumerate} shortens a
+...@code{@@smallexample} line by about 5 columns.
@item
-...@code{@@q...@{@}} --- Single quotes. Used for @q{vague} terms.
+...@code{@@f...@{@dot...@}} --- Use for filenames and directories.
@item
-...@code{@@q...@{@}} --- Double quotes. Used for actual quotes (@qq{he
-said}) or for introducing special input modes.
+...@code{@@opt...@{@dot...@}} --- Use for options to command-line
+commands (eg. @samp{@@opt...@{--format@}}).
@item
-...@code{@@rchan...@{@}} --- link to Changes.
+...@code{@@verbatim} --- Prints the block exactly as it appears in
+the source file (including whitespace, etc.). For program code
+examples, use @code{@@example} instead. @code{@@verbatim} uses
+the same format as @code{@@example}.
-...@item
-...@code{@@rcont...@{@}} --- link to Contributor's Guide.
+Individual lines within an @code{@@verbatim} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@verbatim}
+block is part of an @code{@@item}, individual lines in the
+...@code{@@verbatim} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+...@end itemize
-...@item
-...@code{@@r...@{@}} --- link within current manual (type the exact
-node name inside the @co...@{@}}).
+...@node Indexing
+...@unnumberedsubsubsec Indexing
+
+...@itemize
@item
-...@code{@@res...@{@}} --- link to Engraving Essay.
+...@code{@@cindex @dots{}} --- General index. Please add as many as you can.
+Don't capitalize the first word.
@item
-...@code{@@rext...@{@}} --- link to Extending LilyPond.
+...@code{@@funindex @dots{}} --- is for a \lilycommand.
+...@end itemize
+
+...@node Lists
+...@unnumberedsubsubsec Lists
+
+...@itemize
@item
-...@code{@@rg...@{@}} --- link to the Music Glossary.
+...@code{@@enumerate} --- Create an ordered list (with numbers).
+Always put @samp{@@item} on its own line, and separate consecutive
+items with a blank line:
+
+...@example
+@@enumerate
+@@item
+Foo
+
+@@item
+Bar
+@@end enumerate
+...@end example
@item
-...@code{@@rintern...@{@}} --- link to the Internals Reference.
+...@code{@@itemize} --- Create an unordered list (with bullets). Use
+the same format as @code{@@enumerate}. Do not use
+...@samp{@@item...@tie{}@@bullet}.
+...@end itemize
+
+
+...@node Special characters
+...@unnumberedsubsubsec Special characters
+...@itemize
@item
-...@code{@@rlearn...@{@}} --- link to Learning Manual.
+...@code{--}, @code{---} --- Create an en dash (--) or an em dash
+(---) in the text. To print two or three literal hyphens in a
+row, wrap one of them in a @code{@@w...@{@dot...@}} (eg.
+...@samp{-@@w...@{-@}-}).
@item
-...@code{@@r...@{@}} --- link to a Snippet section.
+...@code{@@@@}, @code{@@@{}, @code{@@@}} --- Create an at-sign (@@),
+a left curly bracket (@{), or a right curly bracket (@}).
@item
-...@code{@@rprog...@{@}} --- link to Application Usage.
+...@code{@@b...@{@}} --- Create a backslash within a
+...@code{@@q...@{@dot...@}}, @code{@@q...@{@dot...@}}, or
+...@code{@@warn...@{@dot...@}} block. This is a custom LilyPond
+macro, not a builtin @@-command in Texinfo. Texinfo would also
+allow @samp{\\}, but this breaks the PDF output.
@item
-...@code{@@ru...@{@}} --- link to Notation Reference.
+...@code{@@t...@{@}} --- Create a @emph{variable-width} non-breaking
+space in the text (use @w...@samp{@@w...@{ @}}} for a single
+...@emph{fixed-width} non-breaking space). 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: @samp{The letter@@t...@{@}@@q...@{i@} is
+skipped}
+...@end itemize
+
+
+...@node Miscellany
+...@unnumberedsubsubsec Miscellany
+...@itemize
@item
-...@code{@@r...@{@}} --- link to General Informaion.
+...@code{@@notat...@{@dot...@}} --- refers to pieces of notation, e.g.
+...@samp{@@notat...@{clef@}}. Also use for specific lyrics
+(@samp{the @@notat...@{a@tie...@tie{}men@} is centered}).
+Only use once per subsection per term.
@item
-...@code{@@t...@{@}} --- 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: @q...@code{the letter@@t...@{@}@@q...@{i@} is skipped}}
+...@code{@@q...@{@dot...@}} --- Single quotes. Used for
+...@quoteleft{}vague@quoteright{} terms. To get a backslash
+(\), you must use @samp{@@b...@{@}}.
@item
-...@code{@@u...@{@}} --- link to an external url.
+...@code{@@q...@{@dot...@}} --- Double quotes. Used for actual quotes
+(@qq{he said}) or for introducing special input modes. To get a
+backslash (\), you must use @samp{@@b...@{@}}.
@item
-...@code{@@var} --- Use for variables.
+...@code{@@v...@{@dot...@}} --- Use for variables.
@item
@code{@@vers...@{@}} --- Return the current LilyPond version
-string.
+string. Use @samp{@@w...@{@@vers...@{@}...@}} if it's at the end of a
+line (to prevent an ugly line break in PDF); use
+...@samp{@@w...@{"@@vers...@{@}"@}} if you need it in quotes.
@item
-...@code{@@warn...@{@}} --- produces a @qq{Note:@tie{}} box. Use for
-important messages.
+...@code{@@w...@{@dot...@}} --- Do not allow any line breaks.
+...@item
+...@code{@@warn...@{@dot...@}} --- produces a @qq{Note:@tie{}} box.
+Use for important messages. To get a backslash (\), you must use
+...@samp{@@b...@{@}}.
@end itemize
-
@node Other text concerns
@subsection Other text concerns
@itemize
-
@item
References must occur at the end of a sentence, for more
-information see @@r...@{the texinfo man...@}. 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.
+information see the
+...@uref{http://www.gnu.org/software/texinfo/manual/texinfo/,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 @code{@@seealso} section at the bottom.
@item
Introducing examples must be done with
@@ -695,30 +770,25 @@ Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
Colon usage
@enumerate
-
@item
To introduce lists
@item
-When beginning a quote: "So, he said,...".
+When beginning a quote: @qq{So, he said,...}.
This usage is rarer. Americans often just use a comma.
@item
When adding a defining example at the end of a sentence.
-
@end enumerate
@item
Non-ASCII characters which are in utf-8 should be directly used;
-this is, don't say @q{Ba@@s...@{@}tuba} but @q{BaÃtuba}. This ensures
-that all such characters appear in all output formats.
-
+this is, don't say @samp{Ba@@s...@{@}tuba} but @samp{BaÃtuba}. This
+ensures that all such characters appear in all output formats.
@end itemize
-
-
@node Documentation policy
@section Documentation policy
--
1.6.3.3
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
