Skip to content

Commit

Permalink
Merge branch 'ja/doc-synopsis-markup'
Browse files Browse the repository at this point in the history 
The way AsciiDoc is used for SYNOPSIS part of the manual pages has
been revamped.  The sources, at least for the simple cases, got
vastly pleasant to work with.

* ja/doc-synopsis-markup:
  doc: apply synopsis simplification on git-clone and git-init
  doc: update the guidelines to reflect the current formatting rules
  doc: introduce a synopsis typesetting
  • Loading branch information
@gitster
gitster committed Oct 10, 2024
2 parents 777489f + 2229389 commit 7994503
Show file tree
Hide file tree
Showing 8 changed files with 209 additions and 107 deletions.
58 changes: 30 additions & 28 deletions Documentation/CodingGuidelines
View file
Original file line number Diff line number Diff line change
Expand Up @@ -828,78 +828,80 @@ Markup:
_<new-branch-name>_
_<template-directory>_

A placeholder is not enclosed in backticks, as it is not a literal.

When needed, use a distinctive identifier for placeholders, usually
made of a qualification and a type:
_<git-dir>_
_<key-id>_

When literal and placeholders are mixed, each markup is applied for
each sub-entity. If they are stuck, a special markup, called
unconstrained formatting is required.
Unconstrained formating for placeholders is __<like-this>__
Unconstrained formatting for literal formatting is ++like this++
`--jobs` _<n>_
++--sort=++__<key>__
__<directory>__++/.git++
++remote.++__<name>__++.mirror++
Git's Asciidoc processor has been tailored to treat backticked text
as complex synopsis. When literal and placeholders are mixed, you can
use the backtick notation which will take care of correctly typesetting
the content.
`--jobs <n>`
`--sort=<key>`
`<directory>/.git`
`remote.<name>.mirror`
`ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`

caveat: ++ unconstrained format is not verbatim and may expand
content. Use Asciidoc escapes inside them.
As a side effect, backquoted placeholders are correctly typeset, but
this style is not recommended.

Synopsis Syntax

Syntax grammar is formatted neither as literal nor as placeholder.
The synopsis (a paragraph with [synopsis] attribute) is automatically
formatted by the toolchain and does not need typesetting.

A few commented examples follow to provide reference when writing or
modifying command usage strings and synopsis sections in the manual
pages:

Possibility of multiple occurrences is indicated by three dots:
_<file>_...
<file>...
(One or more of <file>.)

Optional parts are enclosed in square brackets:
[_<file>_...]
[<file>...]
(Zero or more of <file>.)

++--exec-path++[++=++__<path>__]
An optional parameter needs to be typeset with unconstrained pairs
[<repository>]

--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
brackets.)

[_<patch>_...]
[<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)

Multiple alternatives are indicated with vertical bars:
[`-q` | `--quiet`]
[`--utf8` | `--no-utf8`]
[-q | --quiet]
[--utf8 | --no-utf8]

Use spacing around "|" token(s), but not immediately after opening or
before closing a [] or () pair:
Do: [`-q` | `--quiet`]
Don't: [`-q`|`--quiet`]
Do: [-q | --quiet]
Don't: [-q|--quiet]

Don't use spacing around "|" tokens when they're used to separate the
alternate arguments of an option:
Do: ++--track++[++=++(`direct`|`inherit`)]`
Don't: ++--track++[++=++(`direct` | `inherit`)]
Do: --track[=(direct|inherit)]
Don't: --track[=(direct | inherit)]

Parentheses are used for grouping:
[(_<rev>_ | _<range>_)...]
[(<rev>|<range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)

[(`-p` _<parent>_)...]
[(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.)

`git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
git remote set-head <name> (-a|-d|<branch>)
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.)

And a somewhat more contrived example:
`--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is
Expand Down
20 changes: 20 additions & 0 deletions Documentation/asciidoc.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ ifdef::backend-docbook[]
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}

[literal-inlinemacro]
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

endif::backend-docbook[]

ifdef::backend-docbook[]
Expand Down Expand Up @@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
git-relative-html-prefix=
[linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>

[literal-inlinemacro]
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

endif::backend-xhtml11[]

ifdef::backend-docbook[]
ifdef::doctype-manpage[]
[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
endif::doctype-manpage[]
endif::backend-docbook[]

ifdef::backend-xhtml11[]
[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
endif::backend-xhtml11[]
87 changes: 87 additions & 0 deletions Documentation/asciidoctor-extensions.rb
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
require 'asciidoctor'
require 'asciidoctor/extensions'
require 'asciidoctor/converter/docbook5'
require 'asciidoctor/converter/html5'

module Git
module Documentation
Expand Down Expand Up @@ -39,10 +41,95 @@ def process document, output
output
end
end

class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor

use_dsl
named :synopsis
parse_content_as :simple

def process parent, reader, attrs
outlines = reader.lines.map do |l|
l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
.gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
.gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
.gsub(']', ']{empty}')
end
create_block parent, :verse, outlines, attrs
end
end

class GitDBConverter < Asciidoctor::Converter::DocBook5Converter

extend Asciidoctor::Converter::Config
register_for 'docbook5'

def convert_inline_quoted node
if (type = node.type) == :asciimath
# NOTE fop requires jeuclid to process mathml markup
asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
elsif type == :latexmath
# unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
%(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
elsif type == :monospaced
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
else
open, close, supports_phrase = QUOTE_TAGS[type]
text = node.text
if node.role
if supports_phrase
quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
else
quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
end
else
quoted_text = %(#{open}#{text}#{close})
end
node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
end
end
end

# register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
class GitHTMLConverter < Asciidoctor::Converter::Html5Converter

extend Asciidoctor::Converter::Config
register_for 'html5'

def convert_inline_quoted node
if node.type == :monospaced
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')

else
open, close, tag = QUOTE_TAGS[node.type]
if node.id
class_attr = node.role ? %( class="#{node.role}") : ''
if tag
%(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
else
%(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
end
elsif node.role
if tag
%(#{open.chop} class="#{node.role}">#{node.text}#{close})
else
%(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
end
else
%(#{open}#{node.text}#{close})
end
end
end
end
end
end

Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
block Git::Documentation::SynopsisBlock
postprocessor Git::Documentation::DocumentPostProcessor
end
Loading

0 comments on commit 7994503

Please sign in to comment.