docs: Add links to cmd description from cmd list

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.

Signed-off-by: Noelle Leigh <noelle@noelle.dev>
Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
This commit is contained in:
Noelle Leigh authored and Denys Vlasenko committed 2025-08-03 10:53:20 +02:00
1 parent c2ef7c6dad
commit 26fdc7c6ef
2 files changed
+14 -7

No files matched your search

+2 -2
View File
@@ -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)
+12 -5
View File
@@ -67,30 +67,37 @@ int main(void)
}
if (col == 0) {
col = 6;
printf("\t");
} else {
printf(", ");
}
printf("%s", usage_array[i].aname);
if (usage_array[i].usage[0] != NOUSAGE_STR[0]) {
/*
* If the applet usage string will be included in the final document
* 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;
}