git-scm.com icon indicating copy to clipboard operation
git-scm.com copied to clipboard

Fix list inclusions after .adoc renaming

Open gllghr opened this issue 8 months ago • 0 comments

Changes

This updates scripts/update-docs.rb to account for the change in extension (.txt -> .adoc) when processing include directives during the creation of the en manual pages.

The changes to the generated manual pages can be seen here. I haven't included them in this commit because, looking at the history, it looks like those updates are typically committed separately. Let me know if there's anything else I should do there.

Context

The recent renaming of documentation files from a .txt extension to a .adoc extension broke the generated lists that are included in some of the documentation pages. For example, in the v2.49.0 manual page for git, the sections that are supposed to list all of the subcommands are empty:

...
<h2 id="_high_level_commands_porcelain"><a class="anchor" href="[#_high_level_commands_porcelain](view-source:https://git-scm.com/docs/git/2.49.0#_high_level_commands_porcelain)"></a>High-level commands (porcelain)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We separate the porcelain commands into the main commands and some
ancillary user utilities.</p>
</div>
<div class="sect2">
<h3 id="_main_porcelain_commands"><a class="anchor" href="[#_main_porcelain_commands](view-source:https://git-scm.com/docs/git/2.49.0#_main_porcelain_commands)"></a>Main porcelain commands</h3>

</div>
<div class="sect2">
<h3 id="_ancillary_commands"><a class="anchor" href="[#_ancillary_commands](view-source:https://git-scm.com/docs/git/2.49.0#_ancillary_commands)"></a>Ancillary Commands</h3>
...

We are still generating the command lists with the .txt extension, but the documentation now uses include directives with the .adoc extension, and so we are unable to resolve the includes when we want to expand them:

   build: git-write-tree
   build: git
Documentation/cmds-mainporcelain.adoc could not be resolved for expansion
Documentation/cmds-ancillarymanipulators.adoc could not be resolved for expansion
Documentation/cmds-ancillaryinterrogators.adoc could not be resolved for expansion
Documentation/cmds-foreignscminterface.adoc could not be resolved for expansion
Documentation/cmds-plumbingmanipulators.adoc could not be resolved for expansion
Documentation/cmds-plumbinginterrogators.adoc could not be resolved for expansion
Documentation/cmds-synchingrepositories.adoc could not be resolved for expansion
Documentation/cmds-synchelpers.adoc could not be resolved for expansion
Documentation/cmds-purehelpers.adoc could not be resolved for expansion
Documentation/cmds-guide.adoc could not be resolved for expansion
Documentation/cmds-userinterfaces.adoc could not be resolved for expansion
Documentation/cmds-developerinterfaces.adoc could not be resolved for expansion
   build: gitattributes
   build: gitcli

The other files affected are git-config, git-difftool, and git-merge.

Testing

Ran RERUN=1 ruby ./script/update-docs.rb <path>/git/.git en and confirmed that the 2.49.0 version of the each of the 4 affected pages was updated. Confirmed that no older version or other manual pages were updated. Viewed the updated pages locally to make sure they now included the lists that had been missing.

CC @To1ne

gllghr avatar May 30 '25 19:05 gllghr