man: generate all man pages from POD files when buidling
Subsystems (2)
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 5 lines · Jeffrey Layton
Looks reasonable to me, overall. Do we need a new autoconf test for pod2man?
What should we do if the build host doesn't have it installed? Error out, or disable building the docs?
The latter sounds better. I'll send v2 of this patch.
Signature · 4 lines
Aurélien Aptel / SUSE Labs Samba Team GPG: 1839 CB5F 9F5B FB9B AA97 8C99 03C8 A49B 521B D5D3 SUSE Linux GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): 20170929140303.24880-1-aaptel-IBi9RG/[email protected]
Quoted 50 lines · Aurelien Aptel
Move all man pages to easily editable POD files and generate troff source when building.
Previous .in troff file are still preprocessed before final generation to use configured path (.pod.in -> .pod -> troff). All temporary files (.pod.in and troff sources) are properly deleted on clean.
Remove all troff file, no need to keep generated copies under source control.
This commit does not change the content of the man pages but makes future editing easier.
Adds a new --enable-man/--disable-man configure option to control the generation and installation of man pages. The option is automatically enabled if the system supports it. Explicitely enabling it will make the configure script fail if pod2man is not installed.
Signed-off-by Aurelien Aptel <aaptel-IBi9RG/[email protected]>---
changes in v2:
* add the configure flag for man page generation
* check/autodetect if pod2man is availableMakefile.am | 88 ++-- cifs.idmap.8.in | 101 ----- cifs.idmap.pod.in | 100 +++++ cifs.upcall.8.in | 132 ------ cifs.upcall.pod.in | 147 +++++++ cifscreds.1 | 200 --------- configure.ac | 21 + getcifsacl.1.in | 59 --- getcifsacl.pod.in | 60 +++ idmapwb.8.in | 148 ------- idmapwb.pod => idmapwb.pod.in | 0 mount.cifs.8 | 856 -------------------------------------- mount.cifs.pod | 933 ++++++++++++++++++++++++++++++++++++++++++ pam_cifscreds.8 | 207 ---------- pam_cifscreds.pod | 2 +- setcifsacl.1.in | 113 ----- setcifsacl.pod.in | 117 ++++++ 17 files changed, 1431 insertions(+), 1853 deletions(-) delete mode 100644 cifs.idmap.8.in create mode 100644 cifs.idmap.pod.in delete mode 100644 cifs.upcall.8.in create mode 100644 cifs.upcall.pod.in delete mode 100644 cifscreds.1 delete mode 100644 getcifsacl.1.in
Quoted 8 lines
create mode 100644 getcifsacl.pod.in delete mode 100644 idmapwb.8.in rename idmapwb.pod => idmapwb.pod.in (100%) delete mode 100644 mount.cifs.8 create mode 100644 mount.cifs.pod delete mode 100644 pam_cifscreds.8 delete mode 100644 setcifsacl.1.in create mode 100644 setcifsacl.pod.in
Merged.
Signature · 1 line
Jeff Layton <[email protected]>
Quoted 50 lines · Aurelien Aptel
Move all man pages to easily editable POD files and generate troff source when building.
Previous .in troff file are still preprocessed before final generation to use configured path (.pod.in -> .pod -> troff). All temporary files (.pod.in and troff sources) are properly deleted on clean.
Remove all troff file, no need to keep generated copies under source control.
This commit does not change the content of the man pages but makes future editing easier.
Adds a new --enable-man/--disable-man configure option to control the generation and installation of man pages. The option is automatically enabled if the system supports it. Explicitely enabling it will make the configure script fail if pod2man is not installed.
Signed-off-by Aurelien Aptel <aaptel-IBi9RG/[email protected]>---
changes in v2:
* add the configure flag for man page generation
* check/autodetect if pod2man is availableMakefile.am | 88 ++-- cifs.idmap.8.in | 101 ----- cifs.idmap.pod.in | 100 +++++ cifs.upcall.8.in | 132 ------ cifs.upcall.pod.in | 147 +++++++ cifscreds.1 | 200 --------- configure.ac | 21 + getcifsacl.1.in | 59 --- getcifsacl.pod.in | 60 +++ idmapwb.8.in | 148 ------- idmapwb.pod => idmapwb.pod.in | 0 mount.cifs.8 | 856 -------------------------------------- mount.cifs.pod | 933 ++++++++++++++++++++++++++++++++++++++++++ pam_cifscreds.8 | 207 ---------- pam_cifscreds.pod | 2 +- setcifsacl.1.in | 113 ----- setcifsacl.pod.in | 117 ++++++ 17 files changed, 1431 insertions(+), 1853 deletions(-) delete mode 100644 cifs.idmap.8.in create mode 100644 cifs.idmap.pod.in delete mode 100644 cifs.upcall.8.in create mode 100644 cifs.upcall.pod.in delete mode 100644 cifscreds.1 delete mode 100644 getcifsacl.1.in
Quoted 8 lines
create mode 100644 getcifsacl.pod.in delete mode 100644 idmapwb.8.in rename idmapwb.pod => idmapwb.pod.in (100%) delete mode 100644 mount.cifs.8 create mode 100644 mount.cifs.pod delete mode 100644 pam_cifscreds.8 delete mode 100644 setcifsacl.1.in create mode 100644 setcifsacl.pod.in
Hi Aurelien,
I merged this patch but now I'm having a little buyer's remorse...
I originally used POD docs for some of these because it was easy and I was familiar with it, and I wasn't aware of ReStructuredText.
The kernel however is moving to .rst files, which are just as simple as .pod files to work with, and a bit more standard:
http://docutils.sourceforge.net/docs/user/rst/quickstart.html
Would we be better off moving to RST as the canonical format for the docs here? I think it'd be fairly trivial to do. There is a pod2rst converter already:
http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
A one time conversion to rst files and twiddle the Makefile.am to use rst2man and I think we'd be done. I'm happy to do the work, but I wanted to run it by you in case you had a particular attachment to pod files.
Thanks,
Signature · 1 line
Jeff Layton <[email protected]>
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 3 lines · Jeff Layton
A one time conversion to rst files and twiddle the Makefile.am to use rst2man and I think we'd be done. I'm happy to do the work, but I wanted to run it by you in case you had a particular attachment to pod files.
I've just picked POD because there was already POD files in the tree. You can go ahead if you prefer RST, I personally don't mind much as long as it's not troff :)
Cheers,
Signature · 4 lines
Aurélien Aptel / SUSE Labs Samba Team GPG: 1839 CB5F 9F5B FB9B AA97 8C99 03C8 A49B 521B D5D3 SUSE Linux GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)