Skip to content

Conversation

@technoweenie
Copy link
Contributor

How's this look?

Still needs

  • git media path
  • Add scripts for generating output with ronn.

@technoweenie
Copy link
Contributor Author

Digging this. I think we can go further and describe the server API and the git media pointer file.

@rubyist
Copy link
Contributor

rubyist commented Jun 3, 2014

👍

technoweenie added a commit that referenced this pull request Jun 3, 2014
@technoweenie technoweenie merged commit 1f73d01 into master Jun 3, 2014
@technoweenie technoweenie deleted the man branch June 3, 2014 18:32
@technoweenie technoweenie mentioned this pull request Jun 3, 2014
chrisd8088 added a commit to chrisd8088/git-lfs that referenced this pull request May 15, 2025
The synopsis sections of our manual pages have generally been formatted
in the same way since 2014, when our first manual page was added in
commit 79518af of PR git-lfs#58.  The fixed
portions of the Git LFS command presented in each page's synopsis is
delimited with backticks, and the remainder of the command is left
unformatted.

Our manual page source files were originally written in Ronn and now
use AsciiDoc markup instead.  In both cases, text delimited with backticks
is displayed in a monospace font when our pages are rendered into HTML.
This in itself is consistent with the style we use throughout our manual
pages, as we aim to render all literals as monospace text.

However, we also render all command option flags and argument placeholder
names as monospace text, except within the majority of our synopsis
blocks, where these are displayed in a proportional font.

There are some exceptions, such as in our git-lfs-completion(1),
git-lfs-filter-process(1), and git-lfs-pointer(1) pages, where the entirety
of each line of the synopsis is rendered as monospace text, which is more
consistent with how we display command arguments and flags in the other
sections of our manual pages.

Even in these cases, though, each line of the synopsis is rendered
separately, because we have not placed the entire synopsis within
a literal block.  To prevent the lines being displayed as a continuous
single line, we add trailing hard line breaks in the form of a space
character and a plus ("+") character at the end of the lines.

This is a fragile syntax, though, as can be illustrated by the current
state of our git-lfs-push(1) manual page, where some hard line breaks
were inadvertently omitted when additional lines describing the command's
new --stdin option were inserted into the page's synopsis in commit
e35f407 of PR git-lfs#5086.

We can avoid these types of issues and format our synopsis sections
in a manner consistent with the rest of our manual page text by using
AsciiDoc source listing blocks with custom subtitutions.  We place
all of the command prototypes in each synopsis section into a single
block, which means we can eliminate the trailing hard line breaks
completely.

By using source listing blocks we can support two additional features
which should improve the readability of our manual pages' synopses.
First, we can apply the "quotes" substitution rule, which means we
can format the fixed portions of each command line such that they will
be displayed as bold text when rendered into HTML.  This formatting
aligns with the convention seen used by many Unix manual pages, and
also those of the Git project.

The other feature we can now easily make use of in our synopsis blocks
is the ability to break a single command prototype onto multiple lines,
by indenting the second and subsequent lines so they are clearly
identifiable as parts of a single prototype.  In several subsequent
commits in this PR we will revise some command prototypes so they
are long enough that they will need to be split onto multiple lines,
at which point the ability to indent lines within a single listing
block will be highly advantageous.

Since commit f11d309 of PR git-lfs#5054
our "mangen" utility has recognized AsciiDoc source listing blocks
and rendered them into plain text appropriately.  (Note that we use the
"mangen" utility to convert our manual page source files into formatted
plain text encapsulated in Go string assignments, which are then output
by the "git lfs help" command.)

We expect that in a subsequent commit in this PR we will modify the
"mangen" program to ignore the asterisk character when it appears at
the start or end of a Git LFS command in the new source listing blocks
in our synopsis sections, as for the moment these asterisks will be
rendered literally in the plain text output.

As well, we also expect that in another commit in this PR we will
introduce a small Asciidoctor extention module that will remove the
indentation the current Asciidoctor "manpage" converter always sets
for source listing blocks, but only for the blocks in our synopsis
sections.  This should prevent the synopsis prototypes from appearing
indented by an extra amount when we render our manual page source
files into the roff format.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants