[go: nahoru, domu]
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.

Sign up for GitHub

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

Jump to bottom

[Documentation Feature Request] Split command and config pages #2128

Open
ilmari opened this issue Jul 26, 2023 · 1 comment
Open

[Documentation Feature Request] Split command and config pages #2128

ilmari opened this issue Jul 26, 2023 · 1 comment
Assignees
@dwsteele
Labels
enhancement module [doc]

Comments

@ilmari
Copy link
ilmari commented Jul 26, 2023

The current command and configuration pages are very long and hard to navigate.

Splitting these into one page per top-level section (<div class="section1">) would make navigation and searching for which options/concepts are applicable to a specific command easier, since you don't risk falling through to an unrelated command unexpectedly.
ilmari added a commit to ilmari/pgbackrest-website that referenced this issue Jul 28, 2023
@ilmari
Split command and configuration pages
55cc88f 
Each `<div class="section1">` except the introduction is split into a
page suffixed by the `<span class="id">` value, and the TOC links are
fixed up to match.

Posbile TODOs:

- remove redundant `$section/` prefixes on anchors in the split-out pages
- add up/next/prev links between pages

Fixes pgbackrest/pgbackrest#2128
@ilmari ilmari mentioned this issue Jul 28, 2023
Closed
ilmari added a commit to ilmari/pgbackrest-website that referenced this issue Jul 28, 2023
@ilmari
Split command and configuration pages
98c252f 
Each `<div class="section1">` except the introduction is split into a
page suffixed by the `<span class="id">` value, and the TOC links are
fixed up to match using the `split-doc.pl` script.

Posbile TODOs:

- remove redundant `$section/` prefixes on anchors in the split-out pages
- add javascript to redirect now-broken anchor links to the split-out pages
- add up/next/prev links between pages

Fixes pgbackrest/pgbackrest#2128
ilmari added a commit to ilmari/pgbackrest-website that referenced this issue Jul 28, 2023
@ilmari
Script to split command and configuration pages
effd69b 
Each `<div class="section1">` except the introduction is split into a
page suffixed by the `<span class="id">` value, and the TOC links are
fixed up to match using the `split-doc.pl` script.

Posbile TODOs:

- remove redundant `$section/` prefixes on anchors in the split-out pages
- add javascript to redirect now-broken anchor links to the split-out pages
- add up/next/prev links between pages

Fixes pgbackrest/pgbackrest#2128
@dwsteele dwsteele self-assigned this Aug 21, 2023
@dwsteele
Copy link
Member

This is something we can been contemplating for a while. Not sure if the configuration page is that big a deal, but the command page is certainly too large.

One idea I had is to link command options that are on the configuration page to the configuration page rather than reproducing the entire text. This would shorten the command page by a lot.

Given how we currently generate the documentation, I'm not sure how much more we could do. The current code does not allow separate pages here and updating it is not on our shortlist of things to do. I'd want to get the code migrated to C before making such large changes anyway.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@dwsteele dwsteele

Labels
enhancement module [doc]
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Split command and configuration pages ilmari/pgbackrest-website
2 participants
@ilmari @dwsteele