Skip to content

Fix list inclusions after .adoc renaming #2014

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from

Conversation

gllghr
Copy link

@gllghr gllghr commented May 30, 2025

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

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant