Add AsciiDoc versions of our manual pages · git-lfs/git-lfs@0c66dcf · GitHub
Skip to content

Commit 0c66dcf

Browse files
committed
Add AsciiDoc versions of our manual pages
Our current manual pages use ronn or ronn-ng, which converts pages from a superset of Markdown into manual pages or HTML. This mostly works, but it has some limitations: * ronn-ng requires several dependencies, some of which are C based, which means we must build those on older version of RHEL-compatible OSes. This adds a substantial amount of porting hassle and time to the build. * The superset of Markdown that ronn-ng uses is not rendered correctly on GitHub, leading to difficulties when people view manual pages in the web interface. * Markdown, and the superset ronn-ng uses, don't contain description lists, which are useful for both command options and items in the FAQ, which we'd like to ship in the package. Instead of using Markdown, let's switch to AsciiDoc as the format for manual pages. Asciidoctor, the Ruby version of the command, is written in pure Ruby and is self-contained, and supports HTML 5, XHTML 5, man, and DocBook 5 all in a single program. In addition, it is the library used for rendering AsciiDoc on GitHub, which means that whatever syntax we use is fully supported and should render properly. This commit introduces a simple conversion as the first step, which we'll fix up in several subsequent commits. The Markdown pages remain for now and will be removed in a later commit. This conversion was done using Debian's pandoc 2.9.2.1-3+b2 using the following command: (for i in *.ronn; do pandoc -f commonmark -t asciidoc -o $(basename $(basename $i .1.ronn) .5.ronn).adoc $i; done) Note that during our conversion we remove the number in the manual page name, since Asciidoctor will emit this automatically and we don't want a trailing ".1.1" or ".5.5".
1 parent 5521dc1 commit 0c66dcf

34 files changed

Lines changed: 2321 additions & 0 deletions

‎docs/man/git-lfs-checkout.adoc‎

Lines changed: 80 additions & 0 deletions

‎docs/man/git-lfs-clean.adoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
== git-lfs-clean(1) -- Git clean filter that converts large files to pointers
2+
3+
=== SYNOPSIS
4+
5+
`git lfs clean`
6+
7+
=== DESCRIPTION
8+
9+
Read the contents of a large file from standard input, and write a Git
10+
LFS pointer file for that file to standard output.
11+
12+
Clean is typically run by Git's clean filter, configured by the
13+
repository's Git attributes.
14+
15+
Clean is not part of the user-facing Git plumbing commands. To preview
16+
the pointer of a large file as it would be generated, see the
17+
git-lfs-pointer(1) command.
18+
19+
=== SEE ALSO
20+
21+
git-lfs-install(1), git-lfs-push(1), git-lfs-pointer(1),
22+
gitattributes(5).
23+
24+
Part of the git-lfs(1) suite.

‎docs/man/git-lfs-clone.adoc‎

Lines changed: 53 additions & 0 deletions

0 commit comments

Comments
 (0)