[PATCH 0/2] Convert SubmittingPatches to AsciiDoc
brian m. carlson
2017-10-29 21:13:06 UTC
This series converts SubmittingPatches into AsciiDoc and builds it as
part of the technical documentation.  The goal is to provide a format
that is more easily linkable both from our website and by others, as the
Git Project's patch submission standards are widely referenced and used
as examples.

The decision of what anchors to provide was mostly a matter of judgment,
but as a rule, I provided anchors to anything I've seen referenced in
blog posts or other coding standards.  Opinions on my anchor names are

As explained, I preferred to avoid renaming SubmittingPatches since it's
referred to in so many places, including our own website.  If the list
decides that it's better to just rename, I can do that; it does simplify
the patch somewhat.

The documentation has been tested with both AsciiDoc and Asciidoctor and
looks and functions fine either way.  (I normally use Asciidoctor, but
did test both.)

The first patch is a bridge to help AsciiDoc and Asciidoctor
compatibility.  It enables Asciidoctor's compatibility mode, which
currently has no effect on our codebase[0].  I wrote it thinking that I
would use the AsciiDoc curly quote syntax, but realized that we use the
plain ASCII version everywhere.  It can be kept or dropped, but I hope
that it might avoid some future compatibility issues down the line.  I
had intended to add it originally when writing the USE_ASCIIDOCTOR
support, but it slipped my mind.

I will admit that this series benefits me personally, as I do want to
link to our docs in this way, but I've seen other people want to as
well, and I feel that helping people find documentation on writing
better commit messages and such would be beneficial for the open source
community as a whole.

I expect to be sending a series on top of this one that provides support
for reproducible builds when built with a suitable version of

[0] Running "make clean && make html" results in no changes to the
Documentation directory outside of the change to the Makefile itself.

brian m. carlson (2):
  Documentation: enable compat-mode for Asciidoctor
  Documentation: convert SubmittingPatches to AsciiDoc

 Documentation/.gitignore        |   1 +
 Documentation/Makefile          |   6 +
 Documentation/SubmittingPatches | 331 +++++++++++++++++++++-------------------
 3 files changed, 184 insertions(+), 154 deletions(-)