Skip to content

Commit c7e1ef9

Browse files
vdyevdye
committed
docs/man: add asciidoc manpage content
Add Asciidoc manual pages for 'git-bundle-server' (describing bundle servers in general as well as the tool's individual commands) and 'git-bundle-web-server'. In addition to the Asciidoc pages, add custom 'man:' and 'url:' macros in 'asciidoctor-extensions.rb'. The former is a simplified version of an Asciidoctor example extension [1] (providing basic markup for references to other man pages), while the latter overrides the default autolinking [2] behavior in 'asciidoctor' to avoid some roff rendering weirdness and applies some simple markup. These files are intended for use with Asciidoctor. Documents can be generated with: $ asciidoctor -I scripts/ -r asciidoctor-extensions.rb docs/man/*.adoc In a later commit, these docs will be built into installable manpages as part of a 'Makefile' target. [1] https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/main/lib/man-inline-macro/extension.rb [2] https://docs.asciidoctor.org/asciidoc/latest/macros/autolinks/ Signed-off-by: Victoria Dye <[email protected]>
1 parent 1503992 commit c7e1ef9

File tree

6 files changed

+267
-0
lines changed

6 files changed

+267
-0
lines changed

‎.vscode/settings.json

+8
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,13 @@
1313
"editor.wordWrap": "off",
1414
"files.trimTrailingWhitespace": true,
1515
},
16+
"[asciidoc]": {
17+
"editor.detectIndentation": false,
18+
"editor.insertSpaces": true,
19+
"editor.tabSize": 2,
20+
"editor.wordWrap": "off",
21+
"files.trimTrailingWhitespace": true,
22+
},
1623
"[shellscript]": {
1724
"editor.detectIndentation": false,
1825
"editor.insertSpaces": false,
@@ -21,6 +28,7 @@
2128
"files.trimTrailingWhitespace": true,
2229
},
2330
"files.associations": {
31+
"*.adoc": "asciidoc",
2432
"*.md": "markdown",
2533
"*.sh": "shellscript",
2634
"prerm": "shellscript",

‎docs/man/README.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Man pages
2+
3+
This directory contains Asciidoc-formatted files that are built and installed as
4+
manual pages for the tools in the Git Bundle Server repository.
5+
6+
## File naming
7+
Files with the extension `.adoc` will generate matching `man` page entries
8+
through the `make doc` target. Supplemental content for these files (utilized
9+
via [`include` directives][include]) must _not_ using the `.adoc` extension; the
10+
recommended extension for these files is `.asc`.
11+
12+
[include]: https://docs.asciidoctor.org/asciidoc/latest/directives/include/
13+
14+
## Updating
15+
16+
When major user-facing features of the repository's CLI tools are added or
17+
changed (e.g. new options or subcommands), the corresponding `.adoc` should be
18+
updated to reflect those changes.

‎docs/man/git-bundle-server.adoc

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
= git-bundle-server(1)
2+
:doctype: manpage
3+
:manmanual: Git Bundle Server Manual
4+
:mansource: Git Bundle Server
5+
6+
== NAME
7+
8+
git-bundle-server - create, manage, and host Git bundle content
9+
10+
== SYNOPSIS
11+
[verse]
12+
*git-bundle-server* _command_ [_options_]
13+
14+
== DESCRIPTION
15+
16+
The *git-bundle-server* command-line interface configures, generates, and hosts
17+
Git bundles for use with Git's bundle URI feature (see man:git-bundle[1],
18+
man:git-fetch[1]).
19+
20+
A bundle server is comprised of four main components:
21+
22+
1. the repositories for which bundles are generated
23+
2. the base & incremental bundles for each repository
24+
3. the per-repository lists of those bundles
25+
4. the web server hosting the bundle and bundle-list content
26+
27+
Repositories are initialized in the bundle server with the *init* command, which
28+
clones a specified repository and creates an initial bundle for it.
29+
Initialization also adds the repository to a list of repositories that are
30+
updated by the *update-all* command on a daily man:cron[8] schedule.
31+
32+
New incremental bundles are created when the repository is updated, either
33+
manually (with an invocation of *update* or *update-all*) or automatically (via
34+
the man:cron[8] job). The maximum number of bundles per repository is 5; rather
35+
than creating a sixth bundle, the next update will collapse all bundles into a
36+
new base bundle.
37+
38+
Bundle generation for a repository can be stopped with the *stop* command; if a
39+
user wishes to delete all on-disk resources for a repository, *delete* will
40+
remove all existing bundles and internal repository clone as well.
41+
42+
The bundles generated by this server make use of the 'creationToken' heuristic
43+
to help Git clients avoid downloading bundles they already have.
44+
45+
To serve the generated bundles, the *web-server* command can be used to start or
46+
stop a configured web server. The server will run in the domain of the user that
47+
invoked the command, and will continue running after the user logs out. The
48+
server does not automatically start on system boot (even if it was running
49+
before prior shutdown), so *web-server start* will need to be invoked to restart
50+
the server.
51+
52+
== COMMANDS
53+
54+
*init* _url_ _route_::
55+
Initialize a repository for which bundles should be served. The repository is
56+
cloned into a bare repo from _url_. A base bundle is created for the
57+
repository, served from _route_, and the man:cron[8] global bundle update
58+
schedule is started.
59+
60+
*start* _route_::
61+
Start computing bundles for the repository identified by _route_. If the
62+
man:cron[8] scheduler responsible for periodic bundle updates has not been
63+
configured, this command starts running a global update schedule as well.
64+
65+
*stop* _route_::
66+
Stop computing bundles for the repository identified by _route_.
67+
68+
*update* _route_::
69+
For the repository specified by _route_, fetch the latest content from the
70+
remote and create a new set of bundles and update the bundle list.
71+
72+
*update-all*::
73+
Update all initialized repositories with *git-bundle-server update*. This
74+
command is called via the man:cron[8] scheduler.
75+
76+
*delete* _route_::
77+
Remove a repository configuration and delete its data on disk.
78+
79+
*web-server* *start* [*-f*|*--force*] [_server-options_]::
80+
Start a background process web server hosting bundle metadata and content. The
81+
web server daemon runs under the calling user's domain, and will continue
82+
running after the user logs out.
83+
+
84+
By default, this command does not restart a running web server process or
85+
overwrite an existing web server configuration. To force that behavior, use the
86+
*--force* option.
87+
+
88+
Additionally, users may provide options that configure the execution of
89+
the man:git-bundle-web-server[1] background process.
90+
+
91+
--
92+
*-f*:::
93+
*--force*:::
94+
If the web server daemon has already been configured, stop the running
95+
process if needed and rewrite the configuration before starting the service.
96+
Users should specify this option if they intend to change the web server
97+
configuration (e.g., the port number).
98+
--
99+
+
100+
***
101+
Server options:
102+
+
103+
--
104+
include::server-options.asc[]
105+
--
106+
+
107+
***
108+
109+
*web-server* *stop* [*--remove*]::
110+
Stop the web server background process associated with the current user, if
111+
one is running. Unless the *--remove* option is specified, the service
112+
configuration is left on disk and remains loaded into the system daemon
113+
controller.
114+
115+
*--remove*:::
116+
In addition to stopping a running web server process, fully unload the
117+
service configuration and remove any associated daemon config files from
118+
disk.
119+
120+
== EXAMPLE
121+
122+
Initialize and start generating bundles for the remote repository
123+
url:https://github.com/rust-lang/rust.git[]:
124+
125+
[source,console]
126+
----
127+
$ git-bundle-server init https://github.com/rust-lang/rust.git rust-lang/rust
128+
----
129+
130+
Generate an incremental bundle with latest updates to rust-lang/rust:
131+
132+
[source,console]
133+
----
134+
$ git-bundle-server update rust-lang/rust
135+
----
136+
137+
Start an HTTPS web server on port 443 with certificate 'server.crt' and private
138+
key 'server.key':
139+
140+
[source,console]
141+
----
142+
$ git-bundle-server web-server start --force --port 443 --cert server.crt --key server.key
143+
----
144+
145+
== SEE ALSO
146+
147+
man:git-bundle-web-server[1], man:git-bundle[1], man:git-fetch[1]

‎docs/man/git-bundle-web-server.adoc

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
= git-bundle-web-server(1)
2+
:doctype: manpage
3+
:manmanual: Git Bundle Server Manual
4+
:mansource: Git Bundle Server
5+
6+
== NAME
7+
8+
git-bundle-web-server - run a web server hosting Git bundle content
9+
10+
== SYNOPSIS
11+
[verse]
12+
*git-bundle-web-server* [_server-options_]
13+
14+
== DESCRIPTION
15+
16+
The *git-bundle-web-server* utility runs a web server on the local machine
17+
serving Git bundle content in accordance with Git's bundle URI feature (see
18+
man:git-bundle*[1], man:git-fetch[1]). The process operates under the assumption that
19+
its content is generated by the man:git-bundle-server[1] CLI; unexpected behavior
20+
may result from manually creating, replacing, or removing bundle content.
21+
22+
This program should generally not be called directly by users outside of niche
23+
debugging scenarios. Instead, users are recommended to use *git-bundle-server
24+
web-server* for managing the web server process on their systems.
25+
26+
== OPTIONS
27+
28+
include::server-options.asc[]
29+
30+
== SEE ALSO
31+
32+
man:git-bundle-server[1], man:git-bundle[1], man:git-fetch[1]

‎docs/man/server-options.asc

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
*--port* _port_:::
2+
Configure the web server to run on the given port. By default, the port is
3+
8080.
4+
5+
*--cert* _path_:::
6+
Use the X.509 SSL certificate at the given path to configure the web
7+
server for HTTPS. Must be used with a corresponding private key file
8+
specified with *--key*.
9+
10+
*--key* _path_:::
11+
Use the contents of the specified file as the private key of the X.509 SSL
12+
certificate specified with *--cert*.

‎scripts/asciidoctor-extensions.rb

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
require 'asciidoctor'
2+
require 'asciidoctor/extensions'
3+
4+
module GitBundleServer
5+
module Documentation
6+
class ManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
7+
use_dsl
8+
9+
named :man
10+
name_positional_attributes 'volnum'
11+
12+
def process parent, target, attrs
13+
suffix = (volnum = attrs['volnum']) ? %((#{volnum})) : ''
14+
if parent.document.backend == 'manpage'
15+
# If we're building a manpage, bold the page name
16+
node = create_inline parent, :quoted, target, type: :strong
17+
else
18+
# Otherwise, leave the name as-provided
19+
node = create_inline parent, :quoted, target
20+
end
21+
create_inline parent, :quoted, %(#{node.convert}#{suffix})
22+
end
23+
end
24+
25+
class UrlInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
26+
use_dsl
27+
28+
named :url
29+
30+
def process parent, target, attrs
31+
doc = parent.document
32+
if doc.backend == 'manpage'
33+
# If we're building a manpage, underline the name and escape the URL
34+
# to avoid autolinking (the .URL that Asciidoc creates doesn't
35+
# render correctly on all systems).
36+
escape = target.start_with?( 'http://', 'https://', 'ftp://', 'irc://', 'mailto://') ? '\\' : ''
37+
create_inline parent, :quoted, %(#{escape}#{target}), type: :emphasis
38+
else
39+
# Otherwise, pass through
40+
create_inline parent, :quoted, target
41+
end
42+
end
43+
end
44+
end
45+
end
46+
47+
Asciidoctor::Extensions.register do
48+
inline_macro GitBundleServer::Documentation::ManInlineMacro
49+
inline_macro GitBundleServer::Documentation::UrlInlineMacro
50+
end

0 commit comments

Comments
 (0)