Currently, the titles of the manuals are rendered with a pair of empty
parentheses and no section title:
toolbox(1)() toolbox(1)()
NAME
toolbox - Tool for containerized command line environments...
However, they should be:
toolbox(1) General Commands Manual toolbox(1)
NAME
toolbox - Tool for containerized command line environments...
This is because the troff generated by go-md2man from Markdown has a
faulty invocation of the .TH macro [1]:
.nh
.TH toolbox(1)
.SH NAME
.PP
toolbox - Tool for containerized command line environments on Linux
It should be:
.nh
.TH toolbox 1
.SH NAME
.PP
toolbox - Tool for containerized command line environments on Linux
Original patch from Andrew Denton for Podman [2].
[1] https://www.gnu.org/software/groff/manual/groff.html
[2] Podman commit 63c779a857b55b00
https://github.com/containers/podman/pull/15621https://github.com/containers/toolbox/pull/1210
When describing the --authfile option, the word 'private' is used to
refer to images needing authentication. Using the same word shortens
the text so that the word 'custom' can be used in the same way as in the
other examples.
https://github.com/containers/toolbox/pull/1107
This builds upon commit ea452d7ced.
The configuration of a toolbox container is a higher level topic than
the entry point, and the entry point is mentioned as one part of it.
Therefore, putting the section on toolbox set-up earlier in the text
makes it nicely flow from the DESCRIPTION section into the Entry Point
sub-section.
Emphasize the user-visible features of a toolbox container, and not
the underlying implementation details, and avoid using too much jargon
about container technology.
https://github.com/containers/toolbox/pull/814
It was a deliberate decision to have entry point documented in both
toolbox-create(1) and toolbox-init-container(1). For technical
documentation it's sometimes good to repeat the same thing if it's
sufficiently important. Either to refresh the user's memory or to draw
their attention to it. Having to traverse too many references can get
disorienting. eg., parts of README.md are already repeated in
toolbox(1).
In this case, the entry point is very directly related to the create
command because the command sets it up, and unlike HTML documents,
it's awkward to follow links from manuals.
This reverts parts of commit ea452d7ced.
https://github.com/containers/toolbox/pull/814
The DESCRIPTION already explains the details of the set-up on Fedora,
so there's no need to be so specific here. Plus, conceptually, it's not
meant to be Fedora-specific. Fedora is just an example and happens to
be the most well-supported one at the moment, but that will change.
https://github.com/containers/toolbox/pull/814
- Update "See also" sections
Toolbox does not use Buildah for a considerable time now[0]. We can stop
referencing it in the "See also" sections of the documentation.
In some places mention podman command man pages where they are relevant.
- Add section about toolbox images/containers
Toolbox only supports certain OCI images. These should be documented.
Also, document the change of fedora-toolbox image name.
- Add a section about toolbox container setup
Toolbox containers are specifically configured OCI containers. This
should be documented so that users know what they're using.
- Remove redundant part documentation
The description of what `toolbox init-container` does is already in
toolbox-init-container(1). There's no need to have it in
toolbox-create(1). Instead, replace the text with a hint to visit the
other part of documentation.
- Clarify behaviour of --image option
The fact that Toolbox by default tries to pull from the Fedora
registry[1] should be noted.
- Update synopsis & description of commands
Mention options passed to `podman exec`. Remove redundant paragraph
about container names (is already dealt with in toolbox-create(1)).
There's no need to mention the name of the default container on Fedora
since Toolbox now also supports RHEL.
Mention the default used image on unrecognised systems.
Emphasize the fact that toolboxes are not a fully sandboxed environment.
Update the wording of the description and splits it into a few
subsections.
The description of the --monitor-host was inaccurate and while the
option will go away in the future[2], it is currently in and should be
more documented.
[0] https://github.com/containers/toolbox/pull/160
[1] https://registry.fedoraproject.org
[2] https://github.com/containers/toolbox/pull/617https://github.com/containers/toolbox/pull/512
The Go implementation prefers a newer syntax for assigning a custom
name to a toolbox container. The --container option is still supported
for backwards compatibility, but the manuals should show the new
workflow.
https://github.com/containers/toolbox/pull/678
Ever since version 0.0.10, all newly created toolbox containers use a
reflexive entry point [1] and don't need a user-specific customized
image. Older containers that don't use a reflexive entry point were
deprecated in version 0.0.17 [2], and aren't even supported in the Go
implementation.
Therefore, it's time to finally update the manuals to document the
current way of doing things. Since the reflexive entry point is a key
feature of toolbox containers, some text was added to explain why it's
necessary and what it does.
[1] Commit 8b84b5e460https://github.com/containers/toolbox/pull/160
[2] Commit 9dc5281430https://github.com/containers/toolbox/pull/336https://github.com/containers/toolbox/pull/677
This is meant to allow the user to create toolbox containers of
operating system distributions that are different from that of the
host and isn't Fedora.
https://github.com/containers/toolbox/pull/667
The --candidate-registry is a lesser known option only supported by
the POSIX shell implementation. The Go never implementation never
offered it, and nobody has felt its absence so far. So, it's safe to
assume that there's no urgent need to port it to Go, and it's better to
not confuse users by mentioning it.
https://github.com/containers/toolbox/pull/662
