[LUDOC-394] Use proper names for sections in the manual

• Type: Improvement
• Resolution: Fixed
• Priority: Minor
• Fix Version/s: Lustre 2.14.0 Manual
• Labels: easy
• Assignee: Lustre Manual Triage
• Reporter: Andreas Dilger

Description

Currently, a large number of sections are named with auto-generated section references like dbdoclet.50438199_14978 that have no meaning. Unfortunately, these section references appear in the HTML manual as the relative URL, like http://doc.lustre.org/lustre_manual.xhtml#dbdoclet.50438199_14978

It would be better to give these section references a proper name, like dbdoclet.deactivating_mdt_ost (as is done in patch https://review.whamcloud.com/30864 "LUDOC-305 maintenance: handling full/failed OSTs" in this specific case), but across the whole manual.

Changing these references is relatively straight forward:

• search for dbdoclet.* (or in a few cases section_*)
• for any reference that does not have a descriptive name
  • make up a new name
  • search the rest of the files for the old name
  • replace the old name with the new name

This could be done in a number of smaller patches, so that the whole thing doesn't break if any other patch lands to the manual. While the manual isn't a hotbed of activity, it will probably take too long to do this manually than can be accomplished in a single sitting, and it cannot be done automatically, so better to break it up into smaller chunks.

Issue Links

• is related to: LUDOC-456 Update the xml ids throughout the manual

Comments

[Gerrit Updater]

"Andreas Dilger <[e-mail]>" merged in patch https://review.whamcloud.com/c/doc/manual/+/54170/
Subject: LUDOC-394 manual: Remove extra 'held' word
Project: doc/manual
Branch: master
Current Patch Set:
Commit: 44a25e650ff50a2598e38cb28524a9990ed80ca0

[Gerrit Updater]

"Arshad Hussain <[e-mail]>" uploaded a new patch: https://review.whamcloud.com/c/doc/manual/+/54170
Subject: LUDOC-394 manual: Remove extra 'held' word
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: a513334b5db9895f522ddb58d62b39d3281ff481

[Andreas Dilger]

This has been fixed for all cross references in the manual.

[Gerrit Updater]

Andreas Dilger ([e-mail]) merged in patch https://review.whamcloud.com/43759/
Subject: LUDOC-394 manual: remove 'dbdoclet.' from crossrefs
Project: doc/manual
Branch: master
Current Patch Set:
Commit: c0d5b52c4b61e319d07ec18a12722b44c06d0a5a

[Gerrit Updater]

Andreas Dilger ([e-mail]) uploaded a new patch: https://review.whamcloud.com/43759
Subject: LUDOC-394 manual: remove 'dbdoclet.' from crossrefs
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: 932d6298e0fb2139816597294a6ac7ccc898aed9

[Gerrit Updater]

Andreas Dilger ([e-mail]) merged in patch https://review.whamcloud.com/43444/
Subject: LUDOC-394 manual: Add remaining meaningful ref names
Project: doc/manual
Branch: master
Current Patch Set:
Commit: e5b8f9c749e4cb33fb21baed5ebece0f0b0d6987

[Gerrit Updater]

Andreas Dilger ([e-mail]) merged in patch https://review.whamcloud.com/43443/
Subject: LUDOC-394 manual: Add meaningful ref names under SettingUpBonding.xml
Project: doc/manual
Branch: master
Current Patch Set:
Commit: dd696ea7cee8d65e68465726e24c58f409ff3a5a

[Gerrit Updater]

Andreas Dilger ([e-mail]) merged in patch https://review.whamcloud.com/43442/
Subject: LUDOC-394 manual: Add meaningful ref names under LNetSelfTest.xml
Project: doc/manual
Branch: master
Current Patch Set:
Commit: ab1c86066cb8a75f5b292c820fcb3dc7385217fd

[Gerrit Updater]

Arshad Hussain ([e-mail]) uploaded a new patch: https://review.whamcloud.com/43444
Subject: LUDOC-394 manual: Add remaining meaningful ref names
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: ec2df9a6471f8226eb3070173c41a42200237913

[Gerrit Updater]

Arshad Hussain ([e-mail]) uploaded a new patch: https://review.whamcloud.com/43443
Subject: LUDOC-394 manual: Add meaningful ref names under SettingUpBonding.xml
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: 7c4ee05cdc661bd5d3d55f5f1c19cc3766bdab6b