Improve human readable fallback version of CLI help messages #3921

deivid-rodriguez · 2020-09-01T10:55:51Z

Generating the txt version of man pages with groff is inconvenient for contributors since:

It generates inconsisten output accross groff versions.
It generates a lot of unnecessary whitespace changes when unrelated content changes, making diffs harder to read.

These pages are only built to be able to provide a human readable version of man pages as a fallback when man is not available.

But we can use the original .ronn sources for that.

This PR implements that, and I actually find the new output more readable, so I'm going to sell this as a documentation improvement 😄.

Before:

BUNDLE-OPEN(1)							BUNDLE-OPEN(1)



NAME
       bundle-open - Opens the source directory for a gem in your bundle

SYNOPSIS
       bundle open [GEM]

DESCRIPTION
       Opens the source directory of the provided GEM in your editor.

       For  this to work the EDITOR or BUNDLER_EDITOR environment variable has
       to be set.

       Example:



	   bundle open 'rack'



       Will open the source directory for the 'rack' gem in your bundle.



				 August 2020			BUNDLE-OPEN(1)

After:

$ bundle open --help
bundle-open(1) -- Opens the source directory for a gem in your bundle
=====================================================================

## SYNOPSIS

`bundle open` [GEM]

## DESCRIPTION

Opens the source directory of the provided GEM in your editor.

For this to work the `EDITOR` or `BUNDLER_EDITOR` environment variable has to
be set.

Example:

    bundle open 'rack'

Will open the source directory for the 'rack' gem in your bundle.

Closes #3918.
Closes #3193 as a side effect from removing txt versions of man pages.

Tasks:

Describe the problem / feature
Write tests
Write code to solve the problem
Get code review from coworkers / friends

I will abide by the code of conduct.

deivid-rodriguez · 2020-09-01T11:48:52Z

CI failure should get fixed by ruby/ruby#3497.

deivid-rodriguez · 2020-09-01T12:37:14Z

ruby-core fix was merged. I'll retry CI in 24h to make sure that github actions' ruby-head has picked up the fix.

Since it's easier to update.

It makes it easier for replacing the txt versions, and also consistent since `man/gemfile.5.ronn` is already named with this criteria.

Make `map` actually do something useful.

Use the ronn sources as the human readable fallback.

deivid-rodriguez · 2020-09-04T10:22:41Z

PR rebased. Will merge after CI passes since I can only see upsides and it's a hard PR to keep up to date with the default branch.

eregon · 2020-09-04T21:20:53Z

Thank you!

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

Dead links to source Git happen on both for v2.3 and earlier man pages. This regression has happened since 2020-09-04 with rubygems/rubygems#3921 rubygems/rubygems#3921 but most of them was resolved in PR 542. rubygems#542 Due to missing tags for Bundler 2.0.2 and 2.1.4 on GitHub, we need to link the latest patch versions available on GitHub. Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>

Dead links to source Git happen on both for v2.3 and earlier man pages. This regression has happened since 2020-09-04 with rubygems/rubygems#3921 rubygems/rubygems#3921 but most of them was resolved in PR 542. rubygems#542 Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>

This regression has happened since 2020-09-04 with rubygems/rubygems#3921 - rubygems/rubygems#3921 but most of them was resolved in PR 542. - rubygems#542 Links from each man page will be fixed in PR 615 apart from this - rubygems#615 Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>

Dead links to source Git happen on both for v2.3 and earlier man pages. This regression has happened since 2020-09-04 with rubygems/rubygems#3921 rubygems/rubygems#3921 but most of them was resolved in PR 542. rubygems#542 Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>

This regression has happened since 2020-09-04 with rubygems/rubygems#3921 - rubygems/rubygems#3921 but most of them was resolved in PR 542. - rubygems/bundler-site#542 Links from each man page will be fixed in PR 615 apart from this - rubygems/bundler-site#615 Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>

Dead links to source Git happen on both for v2.3 and earlier man pages. This regression has happened since 2020-09-04 with rubygems/rubygems#3921 rubygems/rubygems#3921 but most of them was resolved in PR 542. rubygems/bundler-site#542 Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>

bundlerbot added Bundler RubyGems labels Sep 1, 2020

deivid-rodriguez added the bundler: minor enhancement label Sep 1, 2020

deivid-rodriguez changed the title ~~Remove txt version of man pages~~ Improve human readable fallback version of CLI help messages Sep 1, 2020

deivid-rodriguez added bundler: documentation and removed bundler: minor enhancement labels Sep 1, 2020

deivid-rodriguez force-pushed the remove_txt_docs branch from b6aac46 to b67d2c2 Compare September 2, 2020 12:27

This was referenced Sep 2, 2020

Catch up with man page naming change in main rubygems/rubygems repo rubygems/bundler-site#532

Merged

Update all references to old repo location to the new one #3264

Closed

The .txt (help) files have malformed ANSI sequences. #3193

Closed

deivid-rodriguez added 6 commits September 4, 2020 11:39

Use unordered list for development setup steps

5d95dd0

Since it's easier to update.

Rename ronn sources to include the man section

38aad09

It makes it easier for replacing the txt versions, and also consistent since `man/gemfile.5.ronn` is already named with this criteria.

Another refactor to man pages building

7be1ea1

Make `map` actually do something useful.

Remove txt version of man pages

5a45d67

Use the ronn sources as the human readable fallback.

Fix typo

ccaaf07

Remove leftover mention to groff

8795edc

deivid-rodriguez force-pushed the remove_txt_docs branch from b67d2c2 to 8795edc Compare September 4, 2020 09:40

deivid-rodriguez merged commit b7cabde into master Sep 4, 2020

deivid-rodriguez deleted the remove_txt_docs branch September 4, 2020 10:54

deivid-rodriguez mentioned this pull request Sep 4, 2020

Readd man pages index #3928

Merged

4 tasks

deivid-rodriguez added a commit that referenced this pull request Oct 5, 2020

Merge pull request #3921 from rubygems/remove_txt_docs

00abffc

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

deivid-rodriguez added a commit that referenced this pull request Oct 5, 2020

Merge pull request #3921 from rubygems/remove_txt_docs

a9dc862

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

deivid-rodriguez added a commit that referenced this pull request Oct 5, 2020

Merge pull request #3921 from rubygems/remove_txt_docs

596b40a

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

dentarg mentioned this pull request Oct 5, 2020

Bundler does not find man pages (looks for txt version) when using ruby-head #3996

Closed

deivid-rodriguez added a commit that referenced this pull request Oct 6, 2020

Merge pull request #3921 from rubygems/remove_txt_docs

a9df682

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

deivid-rodriguez added a commit that referenced this pull request Oct 6, 2020

Merge pull request #3921 from rubygems/remove_txt_docs

761950b

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

deivid-rodriguez added a commit that referenced this pull request Oct 6, 2020

Merge pull request #3921 from rubygems/remove_txt_docs

58273d8

Improve human readable fallback version of CLI help messages (cherry picked from commit b7cabde)

hsbt added a commit to ruby/ruby that referenced this pull request Oct 15, 2020

Partly reverted test failing with rubygems/rubygems#3921

b68c22b

tnir mentioned this pull request Jun 22, 2022

Fix dead links on GitHub from man pages rubygems/bundler-site#615

Merged

tnir mentioned this pull request Jun 23, 2022

Fix dead links to GitHub on README.md rubygems/bundler-site#616

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Improve human readable fallback version of CLI help messages #3921

Improve human readable fallback version of CLI help messages #3921

Uh oh!

deivid-rodriguez commented Sep 1, 2020 •

edited

Loading

Uh oh!

deivid-rodriguez commented Sep 1, 2020

Uh oh!

deivid-rodriguez commented Sep 1, 2020

Uh oh!

deivid-rodriguez commented Sep 4, 2020

Uh oh!

eregon commented Sep 4, 2020

Uh oh!

Uh oh!

Uh oh!

Improve human readable fallback version of CLI help messages #3921

Improve human readable fallback version of CLI help messages #3921

Uh oh!

Conversation

deivid-rodriguez commented Sep 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before:

After:

Tasks:

Uh oh!

deivid-rodriguez commented Sep 1, 2020

Uh oh!

deivid-rodriguez commented Sep 1, 2020

Uh oh!

deivid-rodriguez commented Sep 4, 2020

Uh oh!

eregon commented Sep 4, 2020

Uh oh!

Uh oh!

deivid-rodriguez commented Sep 1, 2020 •

edited

Loading