In the generated `docs/busybox.pod` file, add a link for each command in
the big command list that goes to that command's description, like a
compact table of contents. This seems to only affect the generated HTML
version of the usage page.
To add `id` attributes to each usage section title, each command now
uses `=head2` instead of `=item` for their section heading.
To add links to each command in the list, the list was unindented so
that it could use rich text, and each command was marked as code text
(C<>) so they are styled in monospace. These changes mean that the HTML
and mandoc command list will expand to fit the available width of the
viewport, rather than wrapping at a fixed line-length. The plain text
version retains its existing wrapping behavior.
Because of the new code text formatting, `--quotes=none` was added to
the pod2man and pod2text invocations in Makefile.custom to prevent the
command list from quoting every single command.
---
Makefile.custom | 4 ++--
applets/usage_pod.c | 15 ++++++++++-----
2 files changed, 12 insertions(+), 7 deletions(-)
diff --git a/Makefile.custom b/Makefile.custom
index 6f679c4e1..ea5edb1a8 100644
--- a/Makefile.custom
+++ b/Makefile.custom
@@ -156,12 +156,12 @@ docs/busybox.pod: $(srctree)/docs/busybox_header.pod \
docs/BusyBox.txt: docs/busybox.pod
$(disp_doc)
$(Q)-mkdir -p docs
- $(Q)-pod2text $< > $@
+ $(Q)-pod2text --quotes=none $< > $@
docs/busybox.1: docs/busybox.pod
$(disp_doc)
$(Q)-mkdir -p docs
- $(Q)-pod2man --center=busybox --release="version $(KERNELVERSION)" $< >
$@
+ $(Q)-pod2man --quotes=none --center=busybox --release="version
$(KERNELVERSION)" $< > $@
docs/BusyBox.html: docs/busybox.net/BusyBox.html
$(disp_doc)
diff --git a/applets/usage_pod.c b/applets/usage_pod.c
index 9e6d3f0ee..ab6e20297 100644
--- a/applets/usage_pod.c
+++ b/applets/usage_pod.c
@@ -67,30 +67,35 @@ int main(void)
}
if (col == 0) {
col = 6;
- printf("\t");
} else {
printf(", ");
}
- printf("%s", usage_array[i].aname);
+ /* If the applet usage string will be included in the final
document... */
+ if (usage_array[i].usage[0] != NOUSAGE_STR[0]) {
+ /* ...optimistically link to its header (which is just
the applet name). */
+ printf("L<C<%1$s>|/\"%1$s\">", usage_array[i].aname);
+ } else {
+ /* Without a usage string, just output the applet name
with no link. */
+ printf("C<%s>", usage_array[i].aname);
+ }
col += len2;
}
printf("\n\n");
printf("=head1 COMMAND DESCRIPTIONS\n\n");
- printf("=over 4\n\n");
for (i = 0; i < num_messages; i++) {
if (usage_array[i].aname[0] >= 'a' && usage_array[i].aname[0]
<= 'z'
&& usage_array[i].usage[0] != NOUSAGE_STR[0]
) {
- printf("=item B<%s>\n\n", usage_array[i].aname);
+ /* This is the heading that will be linked from the
command list. */
+ printf("=head2 %s\n\n", usage_array[i].aname);
if (usage_array[i].usage[0])
printf("%s %s\n\n", usage_array[i].aname,
usage_array[i].usage);
else
printf("%s\n\n", usage_array[i].aname);
}
}
- printf("=back\n\n");
return 0;
}
--
2.43.0
_______________________________________________
busybox mailing list
busybox@busybox.net
https://lists.busybox.net/mailman/listinfo/busybox
