Skip to content
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

New manpage format #1921

Open
wants to merge 2 commits into
base: gh-pages
Choose a base branch
from
Open

New manpage format #1921

wants to merge 2 commits into from

Conversation

jnavila
Copy link
Contributor

@jnavila jnavila commented Nov 17, 2024

Changes

This PR changes the way the asciidoc source of manpage is processed, by adding the "synopsis" paragraph style and reworking the backtick format.

Context

The style change has been pushed to master and will be applied to git-clone and git-init in the next version.

@jnavila jnavila changed the base branch from gh-pages to main November 17, 2024 21:57
@dscho
Copy link
Member

dscho commented Nov 18, 2024

I just triggered a pair of workflow runs to update the manual pages and to update the translated manual pages, fetched the result and rendered it locally. Here are two examples:

language before after
English image image
French image image

Personally, I cannot spot any difference, apart from the version number (because this here PR branch is based on v2.46.2 while the updated manual pages include v2.47.0) and the incorrect =<regexp> on the "before" side of the French version (fixed on the "after" side).

Even looking at the HTML of the synopses (taking the French version, so that there is a known difference), I only see this:

diff --git a/before b/after
index 1a87d1348..6185fb72b 100644
--- a/before
+++ b/after
@@ -1,5 +1,5 @@
 <pre class="content"><em>git config list</em> [&lt;option-de-fichier&gt;] [&lt;option-d-affichage&gt;] [--includes]
-<em>git config get</em> [&lt;option-de-fichier&gt;] [&lt;option-d-affichage&gt;] [--includes] [--all] [--regexp=&lt;regexp&gt;] [--value=&lt;valeur&gt;] [--fixed-value] [--default=&lt;default&gt;] &lt;nom&gt;
+<em>git config get</em> [&lt;option-de-fichier&gt;] [&lt;option-d-affichage&gt;] [--includes] [--all] [--regexp] [--value=&lt;valeur&gt;] [--fixed-value] [--default=&lt;default&gt;] &lt;nom&gt;
 <em>git config set</em> [&lt;option-de-fichier&gt;] [--type=&lt;type&gt;] [--all] [--value=&lt;valeur&gt;] [--fixed-value] &lt;nom&gt; &lt;valeur&gt;
 <em>git config unset</em> [&lt;option-de-fichier&gt;] [--all] [--value=&lt;valeur&gt;] [--fixed-value] &lt;nom&gt; &lt;valeur&gt;
 <em>git config rename-section</em> [&lt;option-de-fichier&gt;] &lt;ancien-name&gt; &lt;nouveau-name&gt;

@jnavila what am I missing?

@dscho dscho changed the base branch from main to gh-pages November 18, 2024 19:01
@jnavila jnavila marked this pull request as draft November 18, 2024 21:36
@jnavila
Copy link
Contributor Author

jnavila commented Nov 18, 2024

The manpage of git-config has not been converted yet.
I pushed a branch "test-refactor" on git-html-l10n, where I hand-edited fr/git-add.txt.

After importing, here is the result:

image

I'm not satisfied with the styles, particularly when dealing with inline formats:

image

you can test by yourself locally, and tell me your judgment.

The new style makes the code spans lighter and more integrated into
the text. The new style also makes the code spans more readable and
less intrusive.

Signed-off-by: Jean-Noël Avila <[email protected]>
This commit adds a upcoming manpage format to the AsciiDoc
backend. The new format changes are:

 * The synopsis is now a section with a dedicated style. This
 "synopsis" style allows to automatically format the keywords as
 monospaced and <placeholders> as italic.
 * the backticks are now used to format synopsis-like syntax in inline
 elements.

All the manpages are processed with this format. It may upset the
formatting for older manpages, making it not consistent across a page,
but this will be a mild side effect, as this was not really consistent
before.

Signed-off-by: Jean-Noël Avila <[email protected]>
@jnavila jnavila marked this pull request as ready for review November 30, 2024 16:19
@jnavila
Copy link
Contributor Author

jnavila commented Dec 22, 2024

@dscho I updated the CSS, so it is ready for review.

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.

2 participants