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

Merged
merged 2 commits into from
Jul 2, 2025
Merged

Conversation

gllghr
Copy link
Contributor

@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

gllghr and others added 2 commits July 2, 2025 17:47
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.
Updated via the `update-git-version-and-manual-pages.yml` GitHub workflow.
@dscho dscho force-pushed the fix-cmd-lists2 branch from c10d2f2 to 821864e Compare July 2, 2025 16:08
@dscho
Copy link
Member

dscho commented Jul 2, 2025

I rebased this PR and let the update-git-version-and-manual-pages job do its thing (checking the checkbox labeled "Force re-building all manual pages (e.g. after a script change)").

@dscho dscho linked an issue Jul 2, 2025 that may be closed by this pull request
@dscho dscho merged commit 4b1d7c4 into git:gh-pages Jul 2, 2025
1 check passed
@To1ne
Copy link
Collaborator

To1ne commented Jul 3, 2025

Thanks both for getting this in.

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.

git(1) manual does not list commands
3 participants