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
CentOS Stream 9 has codespell-2.2.1, while so far the 'unit tests' were
being run on Fedora 36, which only has codespell-2.1.0.
This is a step towards testing on CentOS Stream 9.
Fallout from 708fa593e2https://github.com/containers/toolbox/pull/1199
This mirrors the --preserve-fds option of Podman.
Converting an unsigned 'uint', which is what Podman uses for its
--preserve-fds option, to a string is surprisingly annoying.
strconv.Itoa [1] takes a signed 'int', which would require a cast, and
there's no unsigned counterpart. There's strconv.FormatUint [2] which
takes an unsigned 'uint64', which is better, but would still require a
cast.
So, fmt.Sprint [3] it is, if the cast is to be avoided. It's more
expensive than the other two functions, but there's no need to worry
unless it's proven to be a performance bottle neck.
Some changes by Debarshi Ray.
[1] https://pkg.go.dev/strconv#Itoa
[2] https://pkg.go.dev/strconv#FormatUint
[3] https://pkg.go.dev/fmt#Sprinthttps://github.com/containers/toolbox/issues/1066
Signed-off-by: Allison Karlitskaya <allison.karlitskaya@redhat.com>
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
When a command is executed with toolbox run and it returns a non-zero
exit code, it is just ignored if that exit code is not handled. This
prevents users to identify errors when executing commands in toolbox.
With this fix, the exit codes of the invoked command are propagated
and returned by 'toolbox run'. This includes even exit codes returned
by Podman on error.
https://github.com/containers/toolbox/pull/1013
Co-authored-by: Ondřej Míchal <harrymichal@seznam.cz>
This will be used by the subsequent commit to add a page to document
the configuration file, which should go into section 5 of the manual.
https://github.com/containers/toolbox/pull/963
SELinux is always meant to be disabled. The exact location of the code
is a historical accident and isn't meant to imply that SELinux might
be optionally enabled.
https://github.com/containers/toolbox/pull/814
Avoid phrases like "shortcoming of container configuration", because
it makes one wonder why a known shortcoming is even being used or not
being fixed. Immutability also has its advantages for certain
use-cases, and it's beyond the scope of this manual to have a full
blown discussion about the pros and cons of OCI containers. Interested
readers can research that on their own.
https://github.com/containers/toolbox/pull/814
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
Some aspects of the Fedora image are described in toolbox-create(1),
but the exact URL of the image is an implementation detail. As Toolbox
grows, it will become unwieldy to describe these details in the
top-level manual.
https://github.com/containers/toolbox/pull/814
The manuals for the individual commands were already listed above.
The entry point of toolbox containers is prominently documented in
toolbox-create(1) and toolbox-init-container(1). It's not clear why
someone who has just come across toolbox(1) would want to know about
the entry point. It's, after all, an implementation detail. They
probably don't even know what's an entry point to begin with. The
top-level manual should give the reader an overall view of the tool
from a user's perspective, and let the other manuals draw them into the
finer details of things.
https://github.com/containers/toolbox/pull/814
It's good to document the --log-level and --log-podman flags because
they can give us some flexibility with the logging in future, but it's
still desirable to keep --verbose (and the -vv trick) in the manual.
Toolbox is still a small enough code base that not too many log levels
are actually needed, yet. The complexity of remembering which log
level reveals which detail soon starts to outweigh the simplicity of
dumping as much as possible, since there aren't that many log messages
to begin with. It's a lot easier to type and remember things like
--verbose, -v and -vv, than their newer counterparts, and they are a
reasonably widely used convention (eg., flatpak, nmap, ssh, etc.).
If some day Toolbox grows to have a significantly larger number of log
messages, then it's possible that --verbose would be of less use, but
that's not the case today.
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
When taking ownership of the runtime directory or the initialization
stamp file inside it, it was assumed that the user's GID and UID were
the same. However that might not always be the case.
Note that this commit doesn't use the GID passed from the host to the
toolbox container's entry point to configure the user inside the
container. That is actually more difficult than it sounds. The manual
for useradd(8) says that the group specified by the '--gid' flag must
actually exist.
https://github.com/containers/toolbox/issues/664
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/681
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
The Go implementation had deprecated the reset command, right from the
beginning, in favour of 'podman system reset'. It's time to finally
remove it.
https://github.com/containers/toolbox/pull/668
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
