New manpage format #1921
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,63 @@ | ||||||
| require 'asciidoctor' | ||||||
| require 'asciidoctor/extensions' | ||||||
| require 'asciidoctor/converter/html5' | ||||||
|
|
||||||
| module Git | ||||||
| module Documentation | ||||||
| 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}') | ||||||
|
There was a problem hiding this comment. To be honest, I don't know what this one is for. There was a problem hiding this comment. This one is the line that matches all the words which are not placeholders and not grammar signs, and format them as code. These words (in the general sense here) are keywords (option names, enum strings, two or three dot notation, etc). |
||||||
| .gsub(/(<([[:word:]]|[-0-9.])+>)/, '__\\1__') | ||||||
|
There was a problem hiding this comment. I had to dig deep to find what Also why are the inner brackets round brackets? I just wonder if we can simplify to:
Suggested change
And one more question, why the double backslash in the replacement string? There was a problem hiding this comment. The '\w` is for ascii, but here, we are going to process internationalized texts (because placeholders are translated), and this processing requires the special form with double brackets. I'm not an expert in Ruby regexes; this is the form I have found to work well with the translations. As for the using a more generic regex (expecting everything between brackets to be the placeholder's name), the placeholder's names are not supposed to contain spaces, which is perfect when we have to match something like: |
||||||
| .gsub(']', ']{empty}') | ||||||
| end | ||||||
| create_block parent, :verse, outlines, attrs | ||||||
| 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|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>') | ||||||
| .gsub(/(<([[:word:]]|[-0-9.])+>)/, '<em>\1</em>') | ||||||
|
There was a problem hiding this comment. So we more or less need to repeat the regexes here? There was a problem hiding this comment. That's unfortunate, but the two regex are very alike, except that this one processes the text after some pre-processing steps, and the transformations need to be in final result form (with tags and escaped characters). I evaluated the opportunity for factorization, but it makes the code more messy than it is already. |
||||||
| 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 | ||||||
| block Git::Documentation::SynopsisBlock | ||||||
| end | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think a line of comment wouldn't hurt with these regexes. Maybe best with an example:
I think the intended use is for
[...<more>]? Should we include the[and]in the regex?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This line is trying to differentiate the three dots in different contexts, where they have a different meaning and require different formatting.
First there is the form <commit1>...<commit2> when describing a range of commits, where the three dots are a "keyword" understood by git and must be formatted as code.
Then there is the forms used in the grammar to express repetition, such as in "<path> ..." with optionally square brackets, such as "[<path>...]" which usually appear at the end of the command line. These three dots must not be formatted as code, but left as is.
This line matches the former case and forces the corresponding format. I'll add a comment in the same line as yours.