From 849aad2af76768b4884c6dfaaf5907c17408d6e6 Mon Sep 17 00:00:00 2001 From: James Lowe Date: Fri, 24 Jun 2011 20:06:37 +0100 Subject: [PATCH] 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 --- .../contributor/administration.itexi | 8 +- Documentation/contributor/build-notes.itexi | 105 +++++++++--------- Documentation/contributor/doc-work.itexi | 2 + Documentation/contributor/introduction.itexi | 6 +- Documentation/contributor/issues.itexi | 16 +-- Documentation/contributor/lsr-work.itexi | 8 +- .../contributor/programming-work.itexi | 5 +- Documentation/contributor/regressions.itexi | 2 + Documentation/contributor/release-work.itexi | 3 +- Documentation/contributor/source-code.itexi | 4 +- Documentation/contributor/website-work.itexi | 3 +- 11 files changed, 87 insertions(+), 75 deletions(-) diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi index f6cf38194c..9ee46b955e 100644 --- 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 dcb85dad30..16726b1bc2 100644 --- 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 4658c0d74d..5d90b8430f 100644 --- 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 61905d060a..525792b3b1 100644 --- 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 05b31724a8..c51b3f07e9 100644 --- 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 27349b3625..f8ebbbde6a 100644 --- 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 2539ae65a6..c726e63b94 100644 --- 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 45ccbaf760..13c17651b9 100644 --- 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 434dce75dc..ec31472083 100644 --- 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 ba1875c0d6..fee5e36717 100644 --- 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 bb8c19fe94..c356e1146b 100644 --- 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: -- 2.39.2