{"thread":{"id":"9406","subject":"[PATCH] Add support for an info version of the user manual","startedAt":"2007-08-06T10:22:57Z","lastAt":"2008-12-14T14:30:08Z","messageCount":3,"participants":["David Kastrup","Jakub Narebski","Kalle Olavi Niemitalo"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"50009","messageId":"86ir7tc5xk.fsf@lola.quinscape.zz","threadId":"9406","inReplyTo":null,"subject":"[PATCH] Add support for an info version of the user manual","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-06T10:22:57Z","receivedAt":"2007-08-06T10:22:57Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"\nThese patches use docbook2x in order to create an info version of the\ngit user manual.  No existing Makefile targets (including \"all\") are\ntouched, so you need to explicitly say\n\nmake info\nsudo make install-info\n\nto get git.info created and installed.  If the info target directory\ndoes not already contain a \"dir\" file, no directory entry is created.\nThis facilitates $(DESTDIR)-based installations.  The same could be\nachieved with\n\nsudo make INSTALL_INFO=: install-info\n\nexplicitly.\n\nawk is used for patching up sub-par file and directory information in\nthe Texinfo file.  It would be cleaner to place the respective info\nstraight into user-manual.txt or the conversion configurations, but I\nfind myself unable to find out how to do this with Asciidoc/Texinfo.\n\nSigned-off-by: David Kastrup <dak@gnu.org>\n---\n Documentation/Makefile |   28 ++++++++++++++++++++++++++++\n Makefile               |    6 ++++++\n 2 files changed, 34 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 443114b..97ee067 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -44,6 +44,11 @@ INSTALL?=install\n RM ?= rm -f\n DOC_REF = origin/man\n \n+infodir?=$(prefix)/share/info\n+MAKEINFO=makeinfo\n+INSTALL_INFO=install-info\n+DOCBOOK2X_TEXI=docbook2x-texi\n+\n -include ../config.mak.autogen\n -include ../config.mak\n \n@@ -67,6 +72,8 @@ man1: $(DOC_MAN1)\n man5: $(DOC_MAN5)\n man7: $(DOC_MAN7)\n \n+info: git.info\n+\n install: man\n \t$(INSTALL) -d -m755 $(DESTDIR)$(man1dir)\n \t$(INSTALL) -d -m755 $(DESTDIR)$(man5dir)\n@@ -75,6 +82,14 @@ install: man\n \t$(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)\n \t$(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)\n \n+install-info: info\n+\t$(INSTALL) -d -m755 $(DESTDIR)$(infodir)\n+\t$(INSTALL) -m644 git.info $(DESTDIR)$(infodir)\n+\tif test -r $(DESTDIR)$(infodir)/dir; then \\\n+\t  $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\\\n+\telse \\\n+\t  echo \"No directory found in $(DESTDIR)$(infodir)\" >&2 ; \\\n+\tfi\n \n ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE\n \t$(MAKE) -C ../ GIT-VERSION-FILE\n@@ -138,6 +153,19 @@ XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n user-manual.html: user-manual.xml\n \txsltproc $(XSLTOPTS) -o $@ $(XSLT) $<\n \n+git.info: user-manual.xml\n+\t$(RM) $@ $*.texi\n+\t$(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | \\\n+\tawk '/^@setfilename/{$$2=\"git.info\"};\\\n+\t     /^@direntry/{print \"@dircategory Development\"; \\\n+\t                  print \"@direntry\"; \\\n+\t                  print \"* Git: (git).           A fast distributed revision control system\"; \\\n+\t\t\t  print \"@end direntry\"}; \\\n+\t     /^@direntry/,/^@end direntry/ { next }; \\\n+\t     {print}' > $*.texi\n+\t$(MAKEINFO) --no-split $*.texi\n+\t$(RM) $*.texi\n+\n howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n \t$(RM) $@+ $@\n \tsh ./howto-index.sh $(wildcard howto/*.txt) >$@+\ndiff --git a/Makefile b/Makefile\nindex 2f3b9b2..b685c7e 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -913,6 +913,9 @@ perl/Makefile: perl/Git.pm perl/Makefile.PL GIT-CFLAGS\n doc:\n \t$(MAKE) -C Documentation all\n \n+info:\n+\t$(MAKE) -C Documentation info\n+\n TAGS:\n \t$(RM) TAGS\n \t$(FIND) . -name '*.[hcS]' -print | xargs etags -a\n@@ -1005,6 +1008,9 @@ endif\n install-doc:\n \t$(MAKE) -C Documentation install\n \n+install-info:\n+\t$(MAKE) -C Documentation install-info\n+\n quick-install-doc:\n \t$(MAKE) -C Documentation quick-install\n \n-- \n1.5.3.rc4.21.ga63eb\n"},{"id":"50047","messageId":"f985v4$b14$1@sea.gmane.org","threadId":"9406","inReplyTo":"86ir7tc5xk.fsf@lola.quinscape.zz","subject":"Re: [PATCH] Add support for an info version of the user manual","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-08-06T17:44:39Z","receivedAt":"2007-08-06T17:44:39Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"[Cc: David Kastrup <dak@gnu.org>, git@vger.kernel.org]\n\nDavid Kastrup wrote:\n\n> These patches use docbook2x in order to create an info version of the\n> git user manual.\n[...]\n> ---\n>  Documentation/Makefile |   28 ++++++++++++++++++++++++++++\n>  Makefile               |    6 ++++++\n>  2 files changed, 34 insertions(+), 0 deletions(-)\n[...]\n\nFirst, a note on patch: please use $(AWK) instead of 'awk', just in case.\n\nIt would be nice to add a paragraph about build requirements for info\nversion of Git User's Manual in the INSTALL file.\n\nIn the future we would probably want configure.ac to support --with-info or\nsomething like that to install documentation in info format (it does\nsupport --infodir), perhaps with awk autodetection and docbook2x\nautodetection.\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"97879","messageId":"87ljuiu8wf.fsf@Astalo.kon.iki.fi","threadId":"9406","inReplyTo":"86ir7tc5xk.fsf@lola.quinscape.zz","subject":"Re: [PATCH] Add support for an info version of the user manual","fromName":"Kalle Olavi Niemitalo","fromEmail":"kon@iki.fi","sentAt":"2008-12-14T14:30:08Z","receivedAt":"2008-12-14T14:30:08Z","isPatch":true,"sender":{"key":"kon@iki.fi","avatar":null},"body":"David Kastrup <dak@gnu.org> posted to the git mailing list in 2007:\n\n> awk is used for patching up sub-par file and directory information in\n> the Texinfo file.  It would be cleaner to place the respective info\n> straight into user-manual.txt or the conversion configurations, but I\n> find myself unable to find out how to do this with Asciidoc/Texinfo.\n\nI found how to do this, but it's not worth the trouble.\n\nApparently, there are two ways to specify the description for the\nInfo directory entry generated by docbook2X 0.8.3:\n\n(a) Set it in the docbook2x-texi command line, with the option:\n\n    -g description=\"A fast distributed revision control system\"\n\n    This could easily be placed in the Makefile.\n\n(b) Add a /book/bookinfo/abstract[@role=\"texinfo-node\"] element:\n\n    <abstract role=\"texinfo-node\"><simpara>A fast distributed\n    revision control system</simpara></abstract>\n\n    docbook2x-0.8.3/xslt/texi/menudescrip.xsl claims that the role\n    should be \"make-texinfo-node\", but the template in that file\n    actually looks for role=\"texinfo-node\".  docbook2X 0.8.8\n    documents the role correctly.\n\n    The /book/bookinfo element currently comes from the [header]\n    section in docbook.conf of AsciiDoc.  That docbook.conf does\n    not currently provide a way to add an abstract like that.\n    So, Git would have to override the whole header, unless\n    such a feature were added to AsciiDoc.\n\nThen, docbook2x-texi would take the title \"Git User's Manual (for\nversion 1.5.3 or newer)\" and convert it to \"Git User_s Manual\n[for version 1_5_3 or newer]\", presumably to avoid some reserved\ncharacters in Info.  To get a prettier title like \"Git\" in the\nInfo directory entry:\n\n(a) A Git-specific XSL template could read the entry title from\n    /book/bookinfo/titleabbrev, which would also have to be added\n    to the header in the AsciiDoc configuration.\n\n(b) Alternatively, the template could use a command-line parameter.\n    Makefile would provide -g info-dir-title=\"Git\", and the\n    template would then use $info-dir-title.\n\nFinally, to make the Info directory entry link to the right file,\none would have to add -g output-file=git to the docbook2x-texi\ninvocation.\n\nIn summary, it is certainly possible to make AsciiDoc and\ndocbook2X together generate the right kind of directory entry,\nbut I suspect the current Perl hack is more likely to survive\ntoolchain upgrades than a more proper implementation would be.\nIf the necessary features were added to the upstream AsciiDoc\nand docbook2X, then things would be different, but I guess Git\nwouldn't dare require new versions until after a year or so.\n"}]}