delta/git.git/Documentation/Makefile, branch ls/github

Merge branch 'bc/use-asciidoctor-opt'

2017-02-02T21:36:57+00:00

Asciidoctor, an alternative reimplementation of AsciiDoc, still
needs some changes to work with documents meant to be formatted
with AsciiDoc.  "make USE_ASCIIDOCTOR=YesPlease" to use it out of
the box to document our pages is getting closer to reality.

* bc/use-asciidoctor-opt:
  Documentation: implement linkgit macro for Asciidoctor
  Makefile: add a knob to enable the use of Asciidoctor
  Documentation: move dblatex arguments into variable
  Documentation: add XSLT to fix DocBook for Texinfo
  Documentation: sort sources for gitman.texi
  Documentation: remove unneeded argument in cat-texi.perl
  Documentation: modernize cat-texi.perl
  Documentation: fix warning in cat-texi.perl

Documentation: implement linkgit macro for Asciidoctor

2017-01-31T20:18:18+00:00

AsciiDoc uses a configuration file to implement macros like linkgit,
while Asciidoctor uses Ruby extensions.  Implement a Ruby extension that
implements the linkgit macro for Asciidoctor in the same way that
asciidoc.conf does for AsciiDoc.  Adjust the Makefile to use it by
default.

Signed-off-by: brian m. carlson 
Signed-off-by: Junio C Hamano

Makefile: add a knob to enable the use of Asciidoctor

2017-01-23T18:56:57+00:00

While Git has traditionally built its documentation using AsciiDoc, some
people wish to use Asciidoctor for speed or other reasons.  Add a
Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to
produce acceptable output.  For HTML output, XHTML5 was chosen, since
the AsciiDoc options also produce XHTML, albeit XHTML 1.1.

Asciidoctor does not have built-in support for the linkgit macro, but it
is available using the Asciidoctor Extensions Lab.  Add a macro to
enable the use of this extension if it is available.  Without it, the
linkgit macros are emitted into the output.

Signed-off-by: brian m. carlson 
Signed-off-by: Junio C Hamano

Documentation: move dblatex arguments into variable

2017-01-23T18:56:54+00:00

Our dblatex invocation uses several style components from the AsciiDoc
distribution, but those components are not available when building with
Asciidoctor.  Move the command line arguments into a variable so it can
be overridden by the user or makefile configuration options.

Signed-off-by: brian m. carlson 
Signed-off-by: Junio C Hamano

Documentation: add XSLT to fix DocBook for Texinfo

2017-01-23T18:56:53+00:00

There are two ways to create a section in a reference document (i.e.,
manpage) in DocBook 4: refsection elements and refsect, refsect2, and
refsect3 elements.  Either form is acceptable as of DocBook 4.2, but
they cannot be mixed.  Prior to DocBook 4.2, only the numbered forms
were acceptable.

docbook2texi only accepts the numbered forms, and this has not generally
been a problem, since AsciiDoc produces the numbered forms.
Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
5, and uses the unnumbered refsection elements instead.

If we don't convert the unnumbered form to the numbered form,
docbook2texi omits section headings, which is undesirable.  Add an XSLT
stylesheet to transform the unnumbered forms to the numbered forms
automatically, and preprocess the DocBook XML as part of the
transformation to Texinfo format.

Note that this transformation is only necessary for Texinfo, since
docbook2texi provides its own stylesheets.  The DocBook stylesheets,
which we use for other formats, provide the full range of DocBook 4 and
5 compatibility, and don't have this issue.

Signed-off-by: brian m. carlson 
Signed-off-by: Junio C Hamano

Documentation: sort sources for gitman.texi

2017-01-23T18:56:52+00:00

Sorting the sources makes it easier to compare the output using diff.
In addition, it aids groups creating reproducible builds, as the order
of the files is no longer dependent on the file system or other
irrelevant factors.

Signed-off-by: brian m. carlson 
Signed-off-by: Junio C Hamano

asciidoctor: fix user-manual to be built by `asciidoctor`

2017-01-13T18:30:16+00:00

The `user-manual.txt` is designed as a `book` but the `Makefile` wants
to build it as an `article`. This seems to be a problem when building
the documentation with `asciidoctor`. Furthermore the parts *Git
Glossary* and *Appendix B* had no subsections which is not allowed when
building with `asciidoctor`. So lets add a *dummy* section.

Signed-off-by: 마누엘 
Signed-off-by: Johannes Schindelin 
Signed-off-by: Junio C Hamano

Documentation/technical: describe signature formats

2016-06-17T18:39:05+00:00

We use different types of signature formats in different places.
Set up the infrastructure and overview to describe them systematically
in our technical documentation.

Signed-off-by: Michael J Gruber 
Signed-off-by: Junio C Hamano

Documentation: bold literals in man

2016-05-31T18:42:30+00:00

Backticks are emphasized through monospaced styling in the HTML
version of Git documentation. But they were left unstyled in the
manual pages.

To make the man pages more comfortably read, `MAN_BOLD_LITERAL` was
added by 5121a6d (Documentation: option to render literal text as
bold for manpages, 2009-03-27).  It allowed the user to build the
manpages with literals in bold style.

For precaution it was not set by default back then.

Since 79c461d (docs: default to more modern toolset, 2010-11-19), it
is assumed ASCIIDOC 8 and at least docbook-xsl 1.73 are used, so the
need for compatibility concern is much lessor now.

Remove `MAN_BOLD_LITERAL`, and typeset literals as bold by default .
Add `NO_MAN_BOLD_LITERAL`, a new Makefile option, disabling this
feature when defined.

Signed-off-by: Erwan MATHONIERE 
Signed-off-by: Samuel GROOT 
Signed-off-by: Tom RUSSELLO 
Signed-off-by: Matthieu MOY 
Signed-off-by: Junio C Hamano

ci: validate "linkgit:" in documentation

2016-05-10T18:15:04+00:00

It is easy to add incorrect "linkgit:[]" references
to our documentation suite.  Catch these common classes of errors:

 * Referring to Documentation/.txt that does not exist.

 * Referring to a  outside the Git suite.  In general, 
   must begin with "git".

 * Listing the manual  incorrectly.  The first line of the
   Documentation/.txt must end with "()".

with a new script "ci/lint-gitlink", and drive it from "make check-docs".

Signed-off-by: Junio C Hamano