Skip to content

Commit 5d3a8c9

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 9668652 commit 5d3a8c9

File tree

6 files changed

+274
-0
lines changed

6 files changed

+274
-0
lines changed

‎.vscode/settings.json

+9
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,8 @@
2128
"files.trimTrailingWhitespace": true,
2229
},
2330
"files.associations": {
31+
"*.adoc": "asciidoc",
32+
"*.asc": "asciidoc",
2433
"*.md": "markdown",
2534
"*.sh": "shellscript",
2635
"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_ use 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

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
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+
footnote:[Details about the 'creationToken' heuristic can be found in the Git
45+
bundle URIs technical documentation: url:https://git-scm.com/docs/bundle-uri[]].
46+
47+
To serve the generated bundles, the *web-server* command can be used to start or
48+
stop a configured web server. The server will run in the domain of the user that
49+
invoked the command, and will continue running after the user logs out. The
50+
server does not automatically start on system boot (even if it was running
51+
before prior shutdown), so *web-server start* will need to be invoked to restart
52+
the server.
53+
54+
== COMMANDS
55+
56+
*init* _url_ _route_::
57+
Initialize a repository for which bundles should be served. The repository is
58+
cloned into a bare repo from _url_. A base bundle is created for the
59+
repository, served from _route_, and the man:cron[8] global bundle update
60+
schedule is started.
61+
+
62+
It is recommended that users specify an SSH (rather than HTTP) URL for the
63+
_url_ argument to avoid potentially error-causing authentication prompts
64+
while fetching during scheduled bundle updates.
65+
66+
*start* _route_::
67+
Start computing bundles for the repository identified by _route_. If the
68+
man:cron[8] scheduler responsible for periodic bundle updates has not been
69+
configured, this command starts running a global update schedule as well.
70+
71+
*stop* _route_::
72+
Stop computing bundles for the repository identified by _route_.
73+
74+
*update* _route_::
75+
For the repository specified by _route_, fetch the latest content from the
76+
remote and create a new set of bundles and update the bundle list.
77+
78+
*update-all*::
79+
Update all initialized repositories with *git-bundle-server update*. This
80+
command is called via the man:cron[8] scheduler.
81+
82+
*delete* _route_::
83+
Remove a repository configuration and delete its data on disk.
84+
85+
*web-server* *start* [*-f*|*--force*] [_server-options_]::
86+
Start a background process web server hosting bundle metadata and content. The
87+
web server daemon runs under the calling user's domain, and will continue
88+
running after the user logs out.
89+
+
90+
By default, this command does not restart a running web server process or
91+
overwrite an existing web server configuration. To force that behavior, use the
92+
*--force* option.
93+
+
94+
Additionally, users may provide options that configure the execution of
95+
the man:git-bundle-web-server[1] background process.
96+
+
97+
--
98+
*-f*:::
99+
*--force*:::
100+
If the web server daemon has already been configured, stop the running
101+
process if needed and rewrite the configuration before starting the service.
102+
Users should specify this option if they intend to change the web server
103+
configuration (e.g., the port number).
104+
--
105+
+
106+
***
107+
Server options:
108+
+
109+
--
110+
include::server-options.asc[]
111+
--
112+
+
113+
***
114+
115+
*web-server* *stop* [*--remove*]::
116+
Stop the web server background process associated with the current user, if
117+
one is running. Unless the *--remove* option is specified, the service
118+
configuration is left on disk and remains loaded into the system daemon
119+
controller.
120+
121+
*--remove*:::
122+
In addition to stopping a running web server process, fully unload the
123+
service configuration and remove any associated daemon config files from
124+
disk.
125+
126+
== EXAMPLE
127+
128+
Initialize and start generating bundles for the remote repository hosted at
129+
url:https://github.com/rust-lang/rust[]:
130+
131+
[source,console]
132+
----
133+
$ git-bundle-server init [email protected]:rust-lang/rust.git rust-lang/rust
134+
----
135+
136+
Generate an incremental bundle with latest updates to rust-lang/rust:
137+
138+
[source,console]
139+
----
140+
$ git-bundle-server update rust-lang/rust
141+
----
142+
143+
Start an HTTPS web server on port 443 with certificate 'server.crt' and private
144+
key 'server.key':
145+
146+
[source,console]
147+
----
148+
$ git-bundle-server web-server start --force --port 443 --cert server.crt --key server.key
149+
----
150+
151+
== SEE ALSO
152+
153+
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)