From: John Mandereau <john.mandereau@gmail.com>
Date: Thu, 8 May 2008 22:03:41 +0000 (+0200)
Subject: Use doctitle header field of LSR snippets
X-Git-Tag: release/2.11.46-1~16^2~32
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=b7d2e37146970059bc3d5eec537163e7ba64a4c8;p=lilypond.git

Use doctitle header field of LSR snippets

* add and document [doctitle] lilypond-book fragment option,

* define @lydoctitle macro in the proper places,

* test this new feature in NR Pitches,

* update makefiles accordingly,

* thinko: also document texidocLANG feature,

* misc: try to fix 'make clean' in Documentation/user and input/lsr
with `.SECONDARY:'.
---

diff --git a/Documentation/de/user/macros.itexi b/Documentation/de/user/macros.itexi
index 9177b8399c..c76439b9df 100644
--- a/Documentation/de/user/macros.itexi
+++ b/Documentation/de/user/macros.itexi
@@ -113,6 +113,10 @@
 @code{\TEXT\}@c should use internalsref
 @end macro
 
+@macro lydoctitle {TEXT}
+@emph{\TEXT\}
+
+@end macro
 
 @macro funindex {TEXT}
 @findex \TEXT\
diff --git a/Documentation/es/user/macros.itexi b/Documentation/es/user/macros.itexi
index 508870ed61..33ceb7c5cf 100644
--- a/Documentation/es/user/macros.itexi
+++ b/Documentation/es/user/macros.itexi
@@ -118,6 +118,11 @@
 @code{\TEXT\}
 @end macro
 
+@macro lydoctitle {TEXT}
+@emph{\TEXT\}
+
+@end macro
+
 @macro funindex {TEXT}
 @findex \TEXT\
 @kindex \TEXT\
diff --git a/Documentation/fr/user/macros.itexi b/Documentation/fr/user/macros.itexi
index 06f0974a96..77ec3accfb 100644
--- a/Documentation/fr/user/macros.itexi
+++ b/Documentation/fr/user/macros.itexi
@@ -160,6 +160,11 @@
 @code{\TEXT\}
 @end macro
 
+@macro lydoctitle {TEXT}
+@emph{\TEXT\}
+
+@end macro
+
 @macro funindex {TEXT}
 @findex \TEXT\
 @kindex \TEXT\
diff --git a/Documentation/user/GNUmakefile b/Documentation/user/GNUmakefile
index c11ad6c3cb..0247f74b1e 100644
--- a/Documentation/user/GNUmakefile
+++ b/Documentation/user/GNUmakefile
@@ -31,7 +31,7 @@ INFO_IMAGES_DIR = lilypond
 DEST_INFO_IMAGES_SUBDIR = Documentation/user
 endif
 
-STEPMAKE_TEMPLATES=tex texinfo omf documentation
+STEPMAKE_TEMPLATES=texinfo omf documentation
 OMF_FILES += $(outdir)/lilypond-internals.html.omf
 
 LOCALSTEPMAKE_TEMPLATES=lilypond ly
@@ -151,3 +151,5 @@ $(outdir)/lilypond-internals.texi: $(LILYPOND_BINARY)
 ## unused
 $(outdir)/interfaces.itexi: dummy
 	cd $(outdir) && lilypond $(top-src-dir)/ly/generate-interface-doc
+
+.SECONDARY:
diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 4478c0d6cb..599e2ae36d 100644
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -700,6 +700,13 @@ lilypond-book --process="lilypond --format=tex --tex \
 Most LilyPond test documents (in the @file{input} directory of the
 distribution) are small @file{.ly} files which look exactly like this.
 
+For localization purpose, if the Texinfo document contains
+@code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
+contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
+is called with @option{--header=@/texidoc@var{LANG}}, then
+@file{foo@/.texidoc@var{LANG}} will be included instead of
+@file{foo@/.texidoc}.
+
 @item lilyquote
 (Only for Texinfo output.)  This option is similar to quote, but only
 the music snippet (and the optional verbatim block implied by
@@ -707,6 +714,19 @@ the music snippet (and the optional verbatim block implied by
 useful if you want to @code{quote} the music snippet but not the
 @code{texidoc} documentation block.
 
+@item doctitle
+(Only for Texinfo output.) This option works similarly to
+@code{texidoc} option: if @command{lilypond} is called with the
+@option{--header=@/doctitle} option, and the file to be processed is
+called @file{foo@/.ly} and contains a @code{doctitle} field in the
+@code{\header}, it creates a file @file{foo@/.doctitle}.  When
+@code{doctitle} option is used, the contents of @file{foo@/.doctitle},
+which should be a single line of @var{text}, is inserted in the
+Texinfo document as @code{@@lydoctitle @var{text}}.
+@code{@@lydoctitle} should be a macro defined in the Texinfo document.
+The same remark about @code{texidoc} processing with localized
+languages also applies to @code{doctitle}.
+
 @item printfilename
 If a LilyPond input file is included with @code{\lilypondfile}, print
 the file name right before the music snippet.  For HTML output, this
diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi
index 8a47b637cf..0706c52239 100644
--- a/Documentation/user/macros.itexi
+++ b/Documentation/user/macros.itexi
@@ -106,6 +106,11 @@
 
 @end macro
 
+@macro lydoctitle {TEXT}
+@emph{\TEXT\}
+
+@end macro
+
 @macro funindex {TEXT}
 @findex \TEXT\
 @kindex \TEXT\
@@ -347,5 +352,3 @@ program usage manual, @ref{\TEXT\,,,lilypond-program,Application Usage}
 
 @end iftex
 
-
-@c EOF
diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index be22529c7b..cd5d06d6c3 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -322,7 +322,7 @@ cis
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {preventing-extra-naturals-from-being-automatically-added.ly}
 
 @seealso
@@ -648,7 +648,7 @@ see @ref{Instrument transpositions}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 
 
@@ -788,7 +788,7 @@ c2 c
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {tweaking-clef-properties.ly}
 
 
@@ -859,10 +859,10 @@ fis
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {non-traditional-key-signatures.ly}
 
 
@@ -914,7 +914,7 @@ The @code{set-octavation} function also takes -1 (for 8va bassa),
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {ottava-text.ly}
 
 
@@ -1721,7 +1721,7 @@ musicB = {
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
 
 
@@ -1793,10 +1793,10 @@ printed if they are not part of the key signature.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {adding-ambitus-per-voice.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {ambitus-with-multiple-voices.ly}
 
 
@@ -1984,7 +1984,7 @@ the base of the scale is determined by the @code{\key} command.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
 
 @noindent
diff --git a/input/lsr/GNUmakefile b/input/lsr/GNUmakefile
index 6103529167..eacbcb9220 100644
--- a/input/lsr/GNUmakefile
+++ b/input/lsr/GNUmakefile
@@ -2,10 +2,12 @@ depth = ../..
 
 # urg, can't name itely templates foo.itely.in because of standard rule
 
-STEPMAKE_TEMPLATES=documentation texinfo tex
+STEPMAKE_TEMPLATES=documentation texinfo
 LOCALSTEPMAKE_TEMPLATES=lilypond ly
 EXTRA_DIST_FILES += README $(call src-wildcard,*.snippet-list)
 
+default:
+
 ifneq ($(out),)
 MAIN_INFO_DOC = lilypond-snippets
 INFO_DOCS = lilypond-snippets
@@ -14,15 +16,13 @@ INFO_IMAGES_DIR = lilypond-snippets
 DEST_INFO_IMAGES_SUBDIR = input/lsr
 endif
 
-default:
-
 include $(depth)/make/stepmake.make
 
 IN_ITELY_FILES = $(call src-wildcard,*-intro.itely)
 GENERATED_ITELY_FILES = $(IN_ITELY_FILES:%-intro.itely=$(outdir)/%.itely)
 
 $(outdir)/%.itely: %-intro.itely %.snippet-list
-	xargs $(PYTHON) $(buildscript-dir)/lys-to-tely.py -f printfilename,texidoc,verbatim --name=$@ --template=$< < $(filter %.snippet-list, $^)
+	xargs $(PYTHON) $(buildscript-dir)/lys-to-tely.py -f doctitle,texidoc,verbatim --name=$@ --template=$< < $(filter %.snippet-list, $^)
 
 $(outdir)/lilypond-snippets.texi: $(GENERATED_ITELY_FILES) $(LY_FILES)
 
@@ -60,3 +60,5 @@ local-WWW: info $(outdir)/lilypond-snippets.pdf \
   $(outdir)/lilypond-snippets/index.html \
   $(outdir)/lilypond-snippets-big-page.html \
   $(source-links)
+
+.SECONDARY:
diff --git a/input/lsr/lilypond-snippets.tely b/input/lsr/lilypond-snippets.tely
index 538988e13c..b1c28b2af8 100644
--- a/input/lsr/lilypond-snippets.tely
+++ b/input/lsr/lilypond-snippets.tely
@@ -15,6 +15,10 @@
 
 @include version.itexi
 
+@macro lydoctitle{TEXT}
+@section \TEXT\
+@end macro
+
 @dircategory GNU LilyPond --- the music typesetter
 @direntry
 * LilyPond Snippets: (lilypond-snippets).       Short tricks, tips, and examples.
diff --git a/make/lilypond-vars.make b/make/lilypond-vars.make
index 07828e6a9f..c26b1d4219 100644
--- a/make/lilypond-vars.make
+++ b/make/lilypond-vars.make
@@ -32,12 +32,15 @@ LILYPOND_BOOK_INCLUDES = -I $(src-dir)/ -I $(outdir) -I $(input-dir) -I $(input-
 ANTI_ALIAS_FACTOR=2
 LILYPOND_JOBS=$(if $(CPU_COUNT),-djob-count=$(CPU_COUNT),)
 LANG_TEXIDOC_FLAGS:=$(foreach lang,$(LANGS),--header=texidoc$(lang))
+LANG_DOCTITLE_FLAGS:=$(foreach lang,$(LANGS),--header=doctitle$(lang))
 
 LILYPOND_BOOK_LILYPOND_FLAGS=-dbackend=eps \
 --formats=ps,png,pdf \
 $(LILYPOND_JOBS) \
 -dinclude-eps-fonts \
 -dgs-load-fonts \
+--header=doctitle \
+$(LANG_DOCTITLE_FLAGS) \
 --header=texidoc \
 $(LANG_TEXIDOC_FLAGS) \
 -I $(top-src-dir)/input/manual \
diff --git a/scripts/lilypond-book.py b/scripts/lilypond-book.py
index f10e07c172..92618ec52e 100644
--- a/scripts/lilypond-book.py
+++ b/scripts/lilypond-book.py
@@ -247,6 +247,7 @@ QUOTE = 'quote'
 RAGGED_RIGHT = 'ragged-right'
 RELATIVE = 'relative'
 STAFFSIZE = 'staffsize'
+DOCTITLE = 'doctitle'
 TEXIDOC = 'texidoc'
 TEXINFO = 'texinfo'
 VERBATIM = 'verbatim'
@@ -533,6 +534,7 @@ simple_options = [
     NOFRAGMENT,
     NOINDENT,
     PRINTFILENAME,
+    DOCTITLE,
     TEXIDOC,
     LANG,
     VERBATIM,
@@ -1206,10 +1208,14 @@ class LilypondSnippet (Snippet):
         map (consider_file, [base + '.tex',
                              base + '.eps',
                              base + '.texidoc',
-                             base + '.texidoc' + document_language,
+                             base + '.doctitle',
                              base + '-systems.texi',
                              base + '-systems.tex',
                              base + '-systems.pdftexi'])
+        if document_language:
+            map (consider_file,
+                 [base + '.texidoc' + document_language,
+                  base + '.doctitle' + document_language])
 
         # UGH - junk global_options
         if (base + '.eps' in result and self.format in (HTML, TEXINFO)
@@ -1352,6 +1358,13 @@ class LilypondSnippet (Snippet):
     def output_texinfo (self):
         str = self.output_print_filename (TEXINFO)
         base = self.basename ()
+        if DOCTITLE in self.option_dict:
+            doctitle = base + '.doctitle'
+            translated_doctitle = doctitle + document_language
+            if os.path.exists (translated_doctitle):
+                str += '@lydoctitle %s\n' % open (translated_doctitle).read ()
+            elif os.path.exists (doctitle):
+                str += '@lydoctitle %s\n' % open (doctitle).read ()
         if TEXIDOC in self.option_dict:
             texidoc = base + '.texidoc'
             translated_texidoc = texidoc + document_language