Doc: CG remove ugly bars at end of lines in doc

Caused by 'too long' lines in tely/texi files.

Using a variety of methods to break lines that are not normally broken

use @smallexample or ' \ ' in the case of long CLI syntax

Tracker issue 1691

diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi
index f6cf38194ca1a13dc2190b0c9f3244b1f8ff3e67..9ee46b955ea407526edbe098371a400981ceed01 100644 (file)
--- a/Documentation/contributor/administration.itexi
+++ b/Documentation/contributor/administration.itexi
@@ -770,7 +770,9 @@ Capitalization of identifiers: \VoiceOne ?
 @end verbatim
 
 ?  patch here:
+@smallexample
 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html}
+@end smallexample
 
 @item
 Personally, I find it easier to understand when there's a repeated
@@ -828,13 +830,13 @@ sequential-statement to the score."
 
 @item
 Discussion on
-http://code.google.com/p/lilypond/issues/detail?id=1322
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
 about \new vs. \context.
 
 
 @item
 Let users add their own items to the parser?  comment 11 on:
-http://code.google.com/p/lilypond/issues/detail?id=1322
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1322}
 
 @item
 should engravers be pluralized (note_heads_engraver) or not
@@ -842,7 +844,7 @@ should engravers be pluralized (note_heads_engraver) or not
 
 @item
 should we allow numbers in identifier names?  Issue:
-http://code.google.com/p/lilypond/issues/detail?id=1670
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1670}
 
 @item
 should we officially allow accented characters?  in general, how

diff --git a/Documentation/contributor/build-notes.itexi b/Documentation/contributor/build-notes.itexi
index dcb85dad30c1b5232883ac22428116cb78ced854..16726b1bc22ba128bd9844bd811f1d63bc713dba 100644 (file)
--- a/Documentation/contributor/build-notes.itexi
+++ b/Documentation/contributor/build-notes.itexi
@@ -164,9 +164,9 @@ comments, and I'd guess most of it isn't needed.
 We return to @file{stepmake.make}, where we hit the make rule all:
 The first line of this is:
 
-@example
+@smallexample
 -include $(addprefix $(depth)/make/,$(addsuffix -inclusions.make, $(LOCALSTEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which, when the variables are substituted, gives:
 
@@ -181,9 +181,9 @@ error message when the included file doesn't exist).
 
 And the first file doesn't exist.  Nor the second.  Next:
 
-@example
+@smallexample
 -include $(addprefix $(stepdir)/,$(addsuffix -inclusions.make, $(STEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which expands to the following files:
 
@@ -202,9 +202,9 @@ that'll be something else to discover.)
 
 Next in @file{stepmake.make}:
 
-@example
+@smallexample
 include $(addprefix $(stepdir)/,$(addsuffix -vars.make, $(STEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which expands to:
 
@@ -239,10 +239,10 @@ So now we're back to @file{stepmake.make}.
 
 The next lines are
 :
-@example
+@smallexample
 # ugh. need to do this because of PATH :=$(top-src-dir)/..:$(PATH)
 include $(addprefix $(depth)/make/,$(addsuffix -vars.make, $(LOCALSTEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 and the include expands to:
 
@@ -255,12 +255,12 @@ child @code{make} processes to use them.
 
 The final 4 lines of @file{stepmake.make} are:
 
-@example
+@smallexample
 include $(addprefix $(depth)/make/,$(addsuffix -rules.make, $(LOCALSTEPMAKE_TEMPLATES)))
 include $(addprefix $(stepdir)/,$(addsuffix -rules.make, $(STEPMAKE_TEMPLATES)))
 include $(addprefix $(depth)/make/,$(addsuffix -targets.make, $(LOCALSTEPMAKE_TEMPLATES)))
 include $(addprefix $(stepdir)/,$(addsuffix -targets.make, $(STEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which expand as follows:
 
@@ -336,7 +336,7 @@ A bit more info from 27 March.  I've put some error traces into
 following lines actually cause the make to run (putting an error
 call above them - no make; below them - make):
 
-@example
+@smallexample
 ifeq ($(out),www)
 # All web targets, except info image symlinks and info docs are
 # installed in non-recursing target from TOP-SRC-DIR
@@ -344,14 +344,15 @@ install-WWW:
        -$(INSTALL) -m 755 -d $(DESTDIR)$(webdir)
        rsync -rl --exclude='*.signature' $(outdir)/offline-root $(DESTDIR)$(webdir)
        $(MAKE) -C Documentation omf-local-install
-@end example
+@end smallexample
 
 I don't currently understand the @code{ifeq}, since @code{$(out)}
 is empty at this point, but the line starting @code{-$(INSTALL)}
 translates to:
 
 @example
--/usr/bin/python /home/phil/lilypond-git/stepmake/bin/install.py -c -m 755 -d /usr/local/share/doc/lilypond/html
+-/usr/bin/python /home/phil/lilypond-git/stepmake/bin/install.py \
+  -c -m 755 -d /usr/local/share/doc/lilypond/html
 @end example
 
 End of work for Sunday 27th.
@@ -440,9 +441,9 @@ From git grep:
 
 stepmake/stepmake/generic-vars.make has this:
 
-@example
+@smallexample
 LOOP=+$(foreach i, $(SUBDIRS), $(MAKE) PACKAGE=$(PACKAGE) package=$(package) -C $(i) $@ &&) true
-@end example
+@end smallexample
 
 $@ is the name of the target - WWW-1 in this case.
 
@@ -566,26 +567,26 @@ So my assumption seems correct)
 There appear to be about 74 of them.  After all the makefile
 checking, we get this:
 
-@example
+@smallexample
 Updating goal targets....
 Considering target file `WWW-1'.
- File `WWW-1' does not exist.
-  Considering target file `local-WWW-1'.
-   File `local-WWW-1' does not exist.
-    Considering target file `out-www/collated-files.texi'.
-     File `out-www/collated-files.texi' does not exist.
-     Looking for an implicit rule for `out-www/collated-files.texi'.
-     Trying pattern rule with stem `collated-files.texi'.
-     Trying implicit prerequisite `collated-files.texi.in'.
-     Trying pattern rule with stem `collated-files.texi'.
-     Trying implicit prerequisite `collated-files.texi.in'.
-     Trying pattern rule with stem `collated-files'.
-     Trying implicit prerequisite `collated-files.tely'.
-     Trying pattern rule with stem `collated-files'.
-     Trying implicit prerequisite `out-www/collated-files.tely'.
-     Trying rule prerequisite `out-www/version.itexi'.
-     Found prerequisite `out-www/version.itexi' as VPATH `/home/phil/lilypond-git/input/regression/out-www/version.itexi'
-@end example
+File `WWW-1' does not exist.
+Considering target file `local-WWW-1'.
+File `local-WWW-1' does not exist.
+Considering target file `out-www/collated-files.texi'.
+File `out-www/collated-files.texi' does not exist.
+Looking for an implicit rule for `out-www/collated-files.texi'.
+Trying pattern rule with stem `collated-files.texi'.
+Trying implicit prerequisite `collated-files.texi.in'.
+Trying pattern rule with stem `collated-files.texi'.
+Trying implicit prerequisite `collated-files.texi.in'.
+Trying pattern rule with stem `collated-files'.
+Trying implicit prerequisite `collated-files.tely'.
+Trying pattern rule with stem `collated-files'.
+Trying implicit prerequisite `out-www/collated-files.tely'.
+Trying rule prerequisite `out-www/version.itexi'.
+Found prerequisite `out-www/version.itexi' as VPATH `/home/phil/lilypond-git/input/regression/out-www/version.itexi'
+@end smallexample
 
 grep finds this if searching for local-WWW-1:
 
@@ -607,18 +608,18 @@ In ly-rules.make we have:
 
 which I'll work out at some point, and also this rule:
 
-@example
+@smallexample
 $(outdir)/%.texi: $(outdir)/%.tely $(outdir)/version.itexi $(DOCUMENTATION_LOCALE_TARGET) $(INIT_LY_SOURCES) $(SCHEME_SOURCES)
-        LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
-@end example
+  LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
+@end smallexample
 
 Note that the recipe is a very long line - it could probably
 benefit from splitting.  The same makefile also has:
 
-@example
+@smallexample
 $(outdir)/%.texi: $(outdir)/%.tely $(outdir)/version.itexi $(DOCUMENTATION_LOCALE_TARGET) $(INIT_LY_SOURCES) $(SCHEME_SOURCES)
-        LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
-@end example
+  LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
+@end smallexample
 
 @noindent
 which seems to be an almost exact duplicate.  Whatever, the first
@@ -627,7 +628,9 @@ one is executed first.  Have not checked if the second executes.
 The first recipe translates as this:
 
 @example
-LILYPOND_VERSION=2.15.0 /usr/bin/python   --process=' ' --output=./out-www --format= --lily-output-dir /home/phil/lilypond-git/build/out/lybook-db
+LILYPOND_VERSION=2.15.0 /usr/bin/python   --process=' ' \
+  --output=./out-www --format= --lily-output-dir \
+    /home/phil/lilypond-git/build/out/lybook-db
 @end example
 
 @noindent
@@ -638,13 +641,15 @@ of other files.
 
 @example
 DOCUMENTATION_LOCALE_TARGET is blank
-INIT_LY_SOURCES = /home/phil/lilypond-git/scm/auto-beam.scm /home/phil/lilypond-git/scm/autochange.scm
+INIT_LY_SOURCES = /home/phil/lilypond-git/scm/auto-beam.scm \
+  /home/phil/lilypond-git/scm/autochange.scm
 @end example
 
 plus 10s (100s?) of other .scm files.
 
 @example
-SCHEME_SOURCES = /home/phil/lilypond-git/ly/Welcome-to-LilyPond-MacOS.ly /home/phil/lilypond-git/ly/Welcome_to_LilyPond.ly
+SCHEME_SOURCES = /home/phil/lilypond-git/ly/Welcome-to-LilyPond-MacOS.ly \
+  /home/phil/lilypond-git/ly/Welcome_to_LilyPond.ly
 @end example
 
 ditto .ly files.  This does seem a teency bit wrong - it looks like
@@ -669,10 +674,10 @@ Must remake target `out-www/collated-files.tely'
 
 @file{lysdoc-rules.make} has this:
 
-@example
+@smallexample
 $(outdir)/collated-files.tely: $(COLLATED_FILES)
-        $(LYS_TO_TELY) --name=$(outdir)/collated-files.tely --title="$(TITLE)" --author="$(AUTHOR)" $^
-@end example
+       $(LYS_TO_TELY) --name=$(outdir)/collated-files.tely --title="$(TITLE)" --author="$(AUTHOR)" $^
+@end smallexample
 
 @file{lysdoc-vars.make} has:
 
@@ -703,10 +708,10 @@ So the next rule in make is for @file{version.itexi}, and make duly
 checks this.  There's a rule in @file{doc-i18n-root-rules.make} that this
 depends on @file{git/VERSION}:
 
-@example
+@smallexample
 $(outdir)/version.%: $(top-src-dir)/VERSION
-        $(PYTHON) $(top-src-dir)/scripts/build/create-version-itexi.py > $@
-@end example
+       $(PYTHON) $(top-src-dir)/scripts/build/create-version-itexi.py > $@
+@end smallexample
 
 This causes create-version-itexi.py to run and create
 version.itexi.
@@ -1099,9 +1104,9 @@ The options file is @file{/Documentation/lilypond-texi2html.init}.
 This contains *lots* of option and configuration stuff, and also
 includes the line:
 
-@example
+@smallexample
 print STDERR "Initializing settings for web site: [$Texi2HTML::THISDOC@{current_lang@}]\n";
-@end example
+@end smallexample
 
 This is where one of the console messages is generated.
 

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 4658c0d74d3012f23a7867e631bb8a82ac6cbd66..5d90b8430fa9f4574401f64b462bc2429070cc55 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -2163,7 +2163,9 @@ useful) and paste with @key{C-y} or @key{C-v}.
 
 @item Update sections finished in the English documentation; check
 sections status at
+@smallexample
 @uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
+@end smallexample
 
 @item Update documentation PO.  It is recommended not to update
 strings which come from documentation that is currently deeply revised

diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi
index 61905d060af075b5da19421ff26d17ae80b3d4d1..525792b3b19ff7b2aaf3de8bb45020236722defb 100644 (file)
--- a/Documentation/contributor/introduction.itexi
+++ b/Documentation/contributor/introduction.itexi
@@ -29,8 +29,8 @@ help LilyPond.
 @section Overview of work flow
 
 @cartouche
-@strong{Ultra-short summary for Unix developers}: source code is at
-@code{git://git.sv.gnu.org/lilypond.git}.  Documentation is built
+@strong{Short summary for Unix developers}: source code is at
+@uref{git://git.sv.gnu.org/lilypond.git}.  Documentation is built
 with Texinfo, after pre-processing with @code{lilypond-book}.
 Send well-formed patches to @email{lilypond-devel@@gnu.org}.
 @end cartouche
@@ -52,7 +52,7 @@ The @q{official} LilyPond Git repository is hosted by the GNU
 Savannah software forge at @uref{http://git.sv.gnu.org}.
 Although, since Git uses a @emph{distributed} model, technically
 there is no central repository.  Instead, each contributor keeps a
-complete copy of the entire repository (about 116M).
+complete copy of the entire repository (about 116MB).
 
 Changes made within one contributor's copy of the repository can
 be shared with other contributors using @emph{patches}.  A patch

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index 05b31724a8470044c36049d8fb4a7a2b19fd2952..c51b3f07e979d243e445ba330699176ac6200234 100644 (file)
--- a/Documentation/contributor/issues.itexi
+++ b/Documentation/contributor/issues.itexi
@@ -834,17 +834,17 @@ weeks.
 
 Grid view provides the best overview:
 
-@example
+@smallexample
 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
-@end example
+@end smallexample
 
 @subsubheading Hindering development
 
 These issues stop or slow development work:
 
-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
-@end example
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability}
+@end smallexample
 
 @subsubheading Easy tasks
 
@@ -854,9 +854,9 @@ relatively new contributor.  The time given is a quick
 familiar with material in this manual, but does not know anything
 else about LilyPond development.
 
-@example
-@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
-@end example
+@smallexample
+@uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog}
+@end smallexample
 
 @subsubheading Patches to review
 

diff --git a/Documentation/contributor/lsr-work.itexi b/Documentation/contributor/lsr-work.itexi
index 27349b3625c4092a65ffeae9150b4ae1d877ad90..f8ebbbde6a7f366ae636e755ebb30d43700cb274 100644 (file)
--- a/Documentation/contributor/lsr-work.itexi
+++ b/Documentation/contributor/lsr-work.itexi
@@ -148,11 +148,11 @@ master branch, or even better a fresh snapshot from Git master branch.
 @item
 From the top source directory, run:
 
-@example
+@smallexample
 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
-@end example
+@end smallexample
 
 @noindent
 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
@@ -298,7 +298,7 @@ Here is a shell script to run all @file{.ly} files in a directory
 and redirect terminal output to text files, which are then
 searched for the word "failed" to see which snippets do not compile.
 
-@example
+@smallexample
 #!/bin/bash
 
 for LILYFILE in *.ly
@@ -309,4 +309,4 @@ do
 done
 
 grep failed *.txt
-@end example
+@end smallexample

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index 2539ae65a640af3c854363f58e2a95a4605e7151..c726e63b94a767121f65343bc6a96361aa8fd69f 100644 (file)
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -372,16 +372,15 @@ back on a line by themselves.
 
 Command-line script to format stuff with emacs:
 
-@example
+@smallexample
 #!/bin/sh
 emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
-@end example
+@end smallexample
 
 (that's all on one line)
 
 Save it as a shell script, then run on the file(s) you modified.
 
-
 @subheading Indenting with vim
 
 Although emacs indentation is the LilyPond standard, acceptable

diff --git a/Documentation/contributor/regressions.itexi b/Documentation/contributor/regressions.itexi
index 45ccbaf7601351007387766861e2a53d49051e5d..13c17651b9605d3f22b2c254e44c384a9f6bc8aa 100644 (file)
--- a/Documentation/contributor/regressions.itexi
+++ b/Documentation/contributor/regressions.itexi
@@ -430,7 +430,9 @@ code has been exercised by the tests.
 
 For tracking memory usage as part of this test, you will need
 GUILE CVS; especially the following patch:
+@smallexample
 @uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
+@end smallexample
 
 @subheading Code coverage
 

diff --git a/Documentation/contributor/release-work.itexi b/Documentation/contributor/release-work.itexi
index 434dce75dc70842af847e62926cc26b50f9d16f4..ec31472083d65e176c7453ba73fd8ec9c2798ccf 100644 (file)
--- a/Documentation/contributor/release-work.itexi
+++ b/Documentation/contributor/release-work.itexi
@@ -482,7 +482,8 @@ build the specific package(s) you want, i.e.
 @example
 bin/gub mingw::lilypond-installer
 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
-bin/gub --platform=darwin-x86 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
+bin/gub --platform=darwin-x86 \
+  'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
 @end example
 
 or

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index ba1875c0d670392e71c52b1269a6eedc5f3b3e0b..fee5e367174e235ebe08e5c1b3e2406bb3e773fc 100644 (file)
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -65,9 +65,9 @@ Download the @command{lily-git.tcl} script from:
 @c don't change the cgit link below to gitweb; gitweb uses
 @c long filenames like "scripts_auxiliar_lily-git.tcl"
 
-@example
+@smallexample
 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
-@end example
+@end smallexample
 
 @item
 To run the program from the command line, navigate to the

diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi
index bb8c19fe949fc7d4bc8c4e529eea521b5c553105..c356e1146bd5be4aa5918507cdcae1ffc83ee5b2 100644 (file)
--- a/Documentation/contributor/website-work.itexi
+++ b/Documentation/contributor/website-work.itexi
@@ -124,7 +124,7 @@ git merge origin/master
 @end verbatim
 
 Check for any updates to trusted scripts / files:
-
+@smallexample
 @verbatim
 ### check-git.sh
 #!/bin/sh
@@ -160,6 +160,7 @@ cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
 @end verbatim
+@end smallexample
 
 Build the website: