Re: [PATCH] man: generate all man pages from POD files when buidling

Re: [PATCH] man: generate all man pages from POD files when buidling

[Aurélien Aptel]

Jeffrey Layton <jlayton-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org> writes:
> 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.

-- 
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)

Re: [PATCH v2] man: generate all man pages from POD files when buidling

[Jeff Layton]

On Fri, 2017-09-29 at 16:03 +0200, Aurelien Aptel wrote:
> 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/b67k@public.gmane.org>
> ---
> 
> changes in v2:
> 
> * add the configure flag for man page generation
> * check/autodetect if pod2man is available
> 
>  Makefile.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
>  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.
-- 
Jeff Layton <jlayton-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>

Re: [PATCH v2] man: generate all man pages from POD files when buidling

[Jeff Layton]

On Fri, 2017-09-29 at 16:03 +0200, Aurelien Aptel wrote:
> 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/b67k@public.gmane.org>
> ---
> 
> changes in v2:
> 
> * add the configure flag for man page generation
> * check/autodetect if pod2man is available
> 
>  Makefile.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
>  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,
-- 
Jeff Layton <jlayton-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>

Re: [PATCH v2] man: generate all man pages from POD files when buidling

[Aurélien Aptel]

Jeff Layton <jlayton-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org> writes:
> 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,

-- 
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)