build docs from source - asciidoc document attributes

[milahu]

i want to build the manpage git-filter-repo.1 from the source git-filter-repo.txt

the main Makefile has

#
# The remainder of the targets are meant for tasks for the maintainer; if they
# don't work for you, I don't care.  These tasks modify branches and upload
# releases and whatnot, and presume a directory layout I have locally.
#
# ...
update_docs:
        # ...
        # Symlink git-filter-repo.txt documentation into git and build it
        ln -sf ../../git-filter-repo/Documentation/git-filter-repo.txt ../git/Documentation/
        make -C ../git/Documentation -j4 man html
        # ...
        cp -a ../git/Documentation/git-filter-repo.1 $$GIT_WORK_TREE/man1/

but make -C ../git/Documentation -j4 man html requires a Documentation/Makefile
which is not in the repo

git-filter-repo.txt is in asciidoc format (file extension should be .adoc)
so i tried a2x with some document attributes

a2x \
  -a date=10/10/2022 \
  -a manmanual="Git Manual" \
  -a mansource="Git 2.38.0.dirty" \
  --doctype manpage \
  --format manpage \
  Documentation/git-filter-repo.txt

but the result is different... maybe im missing some document attributes?

wget -O Documentation/git-filter-repo.1.expected \
  https://github.com/newren/git-filter-repo/raw/docs/man1/git-filter-repo.1

diff -u Documentation/git-filter-repo.1{,.expected} | head -n50

--- Documentation/git-filter-repo.1
+++ Documentation/git-filter-repo.1.expected
@@ -38,6 +38,7 @@
         [<name_or_email_filtering_options>] [<parent_rewriting_options>]
         [<generic_callback_options>] [<miscellaneous_options>]
 .fi
+.sp
 .SH "DESCRIPTION"
 .sp
 Rapidly rewrite entire repository history using user\-specified filters\&. This is a destructive operation which should not be used lightly; it writes new commits, trees, tags, and blobs corresponding to (but filtered from) the original objects in the repository, then deletes the original history and leaves only the new\&. See the section called \(lqDISCUSSION\(rq for more details on the ramifications of using this tool\&. Several different types of history rewrites are possible; examples include (but are not limited to):
@@ -173,7 +174,8 @@
 .sp -1
 .IP \(bu 2.3
 .\}
-creating replace\-refs (see linkgit:git\-replace[1]) for old commit hashes, which if manually pushed and fetched will allow users to continue to refer to new commits using (unabbreviated) old commit IDs
+creating replace\-refs (see
+\fBgit-replace\fR(1)) for old commit hashes, which if manually pushed and fetched will allow users to continue to refer to new commits using (unabbreviated) old commit IDs
 .RE
 .sp
 .RS 4
@@ -235,7 +237,7 @@
 .RE
 .SS "Filtering based on paths (see also \-\-filename\-callback)"
 .sp
-These options specify the paths to select\&. Note that much like git itself, renames are NOT followed so you may need to specify multiple paths, e\&.g\&. \-\-path olddir/ \-\-path newdir/
+These options specify the paths to select\&. Note that much like git itself, renames are NOT followed so you may need to specify multiple paths, e\&.g\&. \fB\-\-path olddir/ \-\-path newdir/\fR
 .PP
 \-\-invert\-paths
 .RS 4
@@ -274,52 +276,52 @@
 \-\-paths\-from\-file <filename>
 .RS 4
 Specify several path filtering and renaming directives, one per line\&. Lines with
-==>
+\fB==>\fR
 in them specify path renames, and lines can begin with
-literal:
+\fBliteral:\fR
 (the default),
-glob:, or
-regex:
+\fBglob:\fR, or
+\fBregex:\fR
 to specify different matching styles\&. Blank lines and lines starting with a
-#
+\fB#\fR
 are ignored (if you have a filename that you want to filter on that starts with
-literal:,
-#,
-glob:, or

source:

Path shortcuts
~~~~~~~~~~~~~~

--paths-from-file <filename>::
        Specify several path filtering and renaming directives, one
        per line. Lines with `==>` in them specify path renames, and
        lines can begin with `literal:` (the default), `glob:`, or
        `regex:` to specify different matching styles.  Blank lines
        and lines starting with a `#` are ignored (if you have a
        filename that you want to filter on that starts with
        `literal:`, `#`, `glob:`, or `regex:`, then prefix the line
        with 'literal:').

[Elijah Newren]

but make -C ../git/Documentation -j4 man html requires a Documentation/Makefile
which is not in the repo

Right, in particular, the point is to copy the file into a clone of git.git, using the various asciidoc build facilities that it has, and to build the documentation within that repo.

See also PR #477