Major Description
I did an online search for "Lustre lfsck man page" and it returned the first link https://manpages.org/lfsck/8 which is a super ancient lfsck page from 2005 or so. Another top-listed link is https://man.cx/lustre(7).
It would be useful for the DWG to have someone contact these sites and have them scrape man pages from the primary Lustre Git repo or the Github clone so that they are kept uptodate.
There are also Linux man pages hosted at https://linux.die.net/ and https://man7.org/ that would be useful to have them include Lustre man pages online.
Attachments
Activity
Andreas – is there interest in my linting and fixing manpages and/or re-organizing into chapters as Alex proposes above? The DWG can definitely take this on, but I want to confirm that this is desirable on the whole before I get too far along scoping and dividing up this work.
manpages.org: this has no about page, and whois info is obfuscated by cloudflare. I don't have a great path forward here.
man.cx: I sent email to Andreas Gohr who appears to run this site (https://www.splitbrain.org/). On the site he says he updates the site straight from manpages in Debian, but I asked for more info on this so we can come up with a strategy to get newer content here.
die.net: I sent email to Aaron, who appears to be the sysadmin for the site (https://github.com/aaron42net). There is no info on how they scrape their manpages, so hopefully he can fill me in.
man7.org: I sent email to Alejandro Colomar, who is the co-maintainer for this. He has already gotten back to me:
Hi Ellis,
On Mon, Jan 13, 2025 at 03:33:07PM +0000, Ellis Wilson wrote:
> Hi Alejandro,
>
> I am assisting with updating Lustre documentation within the Lustre
> community. Lustre is an HPC filesystem used at >50% of the top 500
> supercomputers in the world. It is not presently in-tree in the
> kernel, but was in staging some years ago, and there is on-going work
> to try to get it back in-tree someday. I'm reaching out to see if
> there is any interest in including Lustre manpages on man7.org? If
> there is no interest or I should discuss this with someone else please
> don't hesitate to say so.
man7.org is Michael Kerrisk's server. You should contact him at
<man-pages@man7.org>. I've CCd him in this email.
> The manpages for Lustre can be found here if you would like to review
> their count or contents:
> https://github.com/lustre/lustre-release/tree/master/lustre/doc
A few suggestions:
- Use subdirectories (man1/, man3/, man5/, man7/, man8/) for the
different chapters. That allows reading the link (.so) pages within
the source repository.
- I found some warnings when linting those pages with the build system
of the Linux man-pages project. Here's a fraction of the logs:
alx@devuan:/srv/alx/src/linux/man-pages/man-pages/main$ make MANDIR=/tmp/man/lustre/lustre-release/lustre/doc lint-man -k
MANDOC .tmp/man/lfs-changelog.1.lint-man.mandoc.touch
mandoc: .tmp/man/lfs-changelog.1:3:88: STYLE: input text line longer than 80 bytes: lfs-changelog, lfs-c...
make: *** [/srv/alx/src/linux/man-pages/man-pages/main/share/mk/lint/man/mandoc.mk:36: .tmp/man/lfs-changelog.1.lint-man.mandoc.touch] Error 1
MANDOC .tmp/man/lfs-find.1.lint-man.mandoc.touch
mandoc: .tmp/man/lfs-find.1:610:2: ERROR: skipping end of block that is not open: RE
mandoc: .tmp/man/lfs-find.1:794:35: STYLE: unterminated quoted argument
mandoc: .tmp/man/lfs-find.1:1:16: WARNING: cannot parse date, using it verbatim: TH 2024-08-15"
make: *** [/srv/alx/src/linux/man-pages/man-pages/main/share/mk/lint/man/mandoc.mk:36: .tmp/man/lfs-find.1.lint-man.mandoc.touch] Error 1
MANDOC .tmp/man/lfs-getsom.1.lint-man.mandoc.touch
mandoc: .tmp/man/lfs-getsom.1:23:2: ERROR: skipping unknown macro: .Ex
mandoc: .tmp/man/lfs-getsom.1:30:2: STYLE: fill mode already enabled, skipping: EE
make: *** [/srv/alx/src/linux/man-pages/man-pages/main/share/mk/lint/man/mandoc.mk:36: .tmp/man/lfs-getsom.1.lint-man.mandoc.touch] Error 1
MANDOC .tmp/man/lfs-hsm.1.lint-man.mandoc.touch
mandoc: .tmp/man/lfs-hsm.1:3:92: STYLE: input text line longer than 80 bytes: hsm_state, hsm_actio...
mandoc: .tmp/man/lfs-hsm.1:27:81: STYLE: input text line longer than 80 bytes: These are a set of l...
make: *** [/srv/alx/src/linux/man-pages/man-pages/main/share/mk/lint/man/mandoc.mk:36: .tmp/man/lfs-hsm.1.lint-man.mandoc.touch] Error 1
MANDOC .tmp/man/lfs-migrate.1.lint-man.mandoc.touch
mandoc: .tmp/man/lfs-migrate.1:153:84: STYLE: input text line longer than 80 bytes: Do not set LMV_HASH_...
mandoc: .tmp/man/lfs-migrate.1:13:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: .tmp/man/lfs-migrate.1:21:2: WARNING: skipping paragraph macro: PP after SH
mandoc: .tmp/man/lfs-migrate.1:178:2: WARNING: skipping paragraph macro: PP empty
mandoc: .tmp/man/lfs-migrate.1:202:2: WARNING: skipping paragraph macro: PP empty
[...]
You probably want to address most of those. If you have any doubts
using the build system of the Linux man-pages project to lint your
own pages, feel free to ask, CCing the mailing list.
> Thank you for your consideration!
>
> Best,
>
> ellis
Have a lovely day!
Alex
Hi Ellis, yes cleaning up the man page style is fine, especially if it is facilitating upstream acceptance. There will also need some changes to the build and packaging to handle the use of subdirectories, but that is fine.
One note - there are already a few patches updating the man page style, so it would be good to review those and get them landed, and/or base further cleanup patches on top of them.