From e0aab07a7c2d53c50f04e349504f95e9d00ece31 Mon Sep 17 00:00:00 2001 From: John Mandereau Date: Wed, 4 Feb 2009 23:23:09 +0100 Subject: [PATCH] Docs: make Snippets TOC effective and split Contributors' Guide at sections * make Snippets TOC anchors for individual snippets effective by creating nodes for each snippet; this produces a lot of duplicate nodes but it works in texi2html; support for makeinfo should be dropped after this change though; * add support for splitting HTML Texinfo output at section level; thanks to Reinhold Kainhofer for the idea and a part of the patch. (cherry picked from commit 2225db4c97bf1d842860658874d66b54ef3c8f5d) --- Documentation/devel/GNUmakefile | 2 + input/lsr/lilypond-snippets.tely | 7 ++ scripts/build/extract_texi_filenames.py | 95 ++++++++++++++++++++----- stepmake/stepmake/texinfo-rules.make | 2 +- 4 files changed, 87 insertions(+), 19 deletions(-) diff --git a/Documentation/devel/GNUmakefile b/Documentation/devel/GNUmakefile index 526b6f163b..dff3a9cb92 100644 --- a/Documentation/devel/GNUmakefile +++ b/Documentation/devel/GNUmakefile @@ -1,5 +1,7 @@ depth = ../.. +XREF_MAP_FLAGS = --split section -I $(abs-src-dir) + STEPMAKE_TEMPLATES = documentation tex texinfo topdocs LOCALSTEPMAKE_TEMPLATES = ly diff --git a/input/lsr/lilypond-snippets.tely b/input/lsr/lilypond-snippets.tely index 797484fb18..0062153a2b 100644 --- a/input/lsr/lilypond-snippets.tely +++ b/input/lsr/lilypond-snippets.tely @@ -15,12 +15,19 @@ @include version.itexi +@ifnothtml @macro lydoctitle{TEXT} @unnumberedsec \TEXT\ @end macro +@end ifnothtml @ifhtml +@macro lydoctitle{TEXT} +@node \TEXT\ +@unnumberedsec \TEXT\ +@end macro + @ifset bigpage @macro rlearning{NAME} diff --git a/scripts/build/extract_texi_filenames.py b/scripts/build/extract_texi_filenames.py index 5798d5dab2..8848b40511 100644 --- a/scripts/build/extract_texi_filenames.py +++ b/scripts/build/extract_texi_filenames.py @@ -26,30 +26,63 @@ import re import os import getopt -optlist, args = getopt.getopt (sys.argv[1:],'o:') -files = args +options_list, files = getopt.getopt (sys.argv[1:],'o:s:hI:', + ['output=', 'split=', 'help', 'include=']) + +help_text = r"""Usage: %(program_name)s [OPTIONS]... TEXIFILE... +Extract files names for texinfo (sub)sections from the texinfo files. + +Options: + -h, --help print this help + -I, --include=DIRECTORY append DIRECTORY to include search path + -o, --output=DIRECTORY write .xref-map files to DIRECTORY + -s, --split=MODE split manual according to MODE. Possible values + are section and custom (default) +""" + +def help (text): + sys.stdout.write ( text) + sys.exit (0) outdir = '.' -for x in optlist: - if x[0] == '-o': - outdir = x[1] +split = "custom" +include_path = [] +for opt in options_list: + o = opt[0] + a = opt[1] + if o == '-h' or o == '--help': + help (help_text % vars ()) + if o == '-I' or o == '--include': + if os.path.isdir (a): + include_path.append (a) + elif o == '-o' or o == '--output': + outdir = a + elif o == '-s' or o == '--split': + split = a + else: + raise Exception ('unknown option: ' + o) + if not os.path.isdir (outdir): if os.path.exists (outdir): os.unlink (outdir) os.makedirs (outdir) -include_re = re.compile (r'@include ((?!../lily-).*?)\.texi$', re.M) +include_re = re.compile (r'@include ((?!../lily-).*?\.i?texi)$', re.M) whitespaces = re.compile (r'\s+') section_translation_re = re.compile ('^@(node|(?:unnumbered|appendix)\ (?:(?:sub){0,2}sec)?|top|chapter|(?:sub){0,2}section|\ -(?:major|chap|(?:sub){0,2})heading|translationof) (.*?)\\s*$', re.MULTILINE) +(?:major|chap|(?:sub){0,2})heading|translationof|lydoctitle) (.*?)\\s*$', re.MULTILINE) def expand_includes (m, filename): - filepath = os.path.join (os.path.dirname (filename), m.group(1)) + '.texi' + filepath = os.path.join (os.path.dirname (filename), m.group(1)) if os.path.exists (filepath): return extract_sections (filepath)[1] else: + for directory in include_path: + filepath = os.path.join (directory, m.group(1)) + if os.path.exists (filepath): + return extract_sections (filepath)[1] print "Unable to locate include file " + filepath return '' @@ -114,7 +147,26 @@ def remove_texinfo (title): def create_texinfo_anchor (title): return texinfo_file_name (remove_texinfo (title)) -unnumbered_re = re.compile (r'unnumbered.*') +unnumbered_re = re.compile (r'unnumbered.+|lydoctitle') +file_name_section_level = { + 'top': 4, + 'chapter':3, + 'unnumbered':3, + 'appendix':3, + 'section':2, + 'unnumberedsec':2, + 'appendixsec':2, + 'subsection':1, + 'unnumberedsubsec':1, + 'appendixsubsec':1, + 'subsubsection':0, + 'unnumberedsubsubsec':0, + 'appendixsubsubsec':0 +} +if split in file_name_section_level: + splitting_level = file_name_section_level[split] +else: + splitting_level = -1 def process_sections (filename, lang_suffix, page): sections = section_translation_re.findall (page) basename = os.path.splitext (os.path.basename (filename))[0] @@ -129,7 +181,7 @@ def process_sections (filename, lang_suffix, page): for sec in sections: if sec[0] == "node": # Write out the cached values to the file and start a new section: - if this_title != '' and this_title != 'Top': + if this_title and this_title != 'Top': f.write (this_title + "\t" + this_filename + "\t" + this_anchor + "\n") had_section = False this_title = remove_texinfo (sec[1]) @@ -143,23 +195,30 @@ def process_sections (filename, lang_suffix, page): this_filename = anchor else: # Some pages might not use a node for every section, so treat this - # case here, too: If we already had a section and encounter enother + # case here, too: If we already had a section and encounter another # one before the next @node, we write out the old one and start # with the new values - if had_section and this_title != '': + if had_section and this_title: f.write (this_title + "\t" + this_filename + "\t" + this_anchor + "\n") this_title = remove_texinfo (sec[1]) this_anchor = create_texinfo_anchor (sec[1]) had_section = True - # unnumbered nodes use the previously used file name, only numbered - # nodes get their own filename! However, top-level @unnumbered - # still get their own file. - this_unnumbered = unnumbered_re.match (sec[0]) - if not this_unnumbered or sec[0] == "unnumbered": + if split == 'custom': + # unnumbered nodes use the previously used file name, only numbered + # nodes get their own filename! However, top-level @unnumbered + # still get their own file. + this_unnumbered = unnumbered_re.match (sec[0]) + if not this_unnumbered: + this_filename = this_anchor + elif split == 'node': this_filename = this_anchor + else: + if sec[0] in file_name_section_level and \ + file_name_section_level[sec[0]] >= splitting_level: + this_filename = this_anchor - if this_title != '' and this_title != 'Top': + if this_title and this_title != 'Top': f.write (this_title + "\t" + this_filename + "\t" + this_anchor + "\n") f.close () diff --git a/stepmake/stepmake/texinfo-rules.make b/stepmake/stepmake/texinfo-rules.make index 4722b0a9d0..10ceb5c710 100644 --- a/stepmake/stepmake/texinfo-rules.make +++ b/stepmake/stepmake/texinfo-rules.make @@ -68,7 +68,7 @@ $(outdir)/%.txt: $(outdir)/%.texi $(outdir)/version.itexi $(MAKEINFO) -I$(src-dir) -I$(outdir) --no-split --no-headers --output $@ $< $(XREF_MAPS_DIR)/%.xref-map: $(outdir)/%.texi - $(buildscript-dir)/extract_texi_filenames -o $(XREF_MAPS_DIR) $< + $(buildscript-dir)/extract_texi_filenames $(XREF_MAP_FLAGS) -o $(XREF_MAPS_DIR) $< $(outdir)/%.texi: %.texi cp -f $< $@ -- 2.39.5