-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Add man pages #58
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Add man pages #58
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Author
|
Digging this. I think we can go further and describe the server API and the git media pointer file. |
Contributor
|
👍 |
Closed
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
How's this look?
Still needs
git media path