* Re: [PATCH] man: generate all man pages from POD files when buidling
[not found] ` <1506431475.3182.4.camel-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>
@ 2017-09-26 14:50 ` Aurélien Aptel
0 siblings, 0 replies; 4+ messages in thread
From: Aurélien Aptel @ 2017-09-26 14:50 UTC (permalink / raw
To: Jeffrey Layton, linux-cifs-u79uwXL29TY76Z2rM5mHXA
Cc: smfrench-Re5JQEeQqe8AvxtiuMwx3w
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)
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v2] man: generate all man pages from POD files when buidling
[not found] ` <20170929140303.24880-1-aaptel-IBi9RG/b67k@public.gmane.org>
@ 2017-10-06 10:37 ` Jeff Layton
2017-10-23 12:31 ` Jeff Layton
1 sibling, 0 replies; 4+ messages in thread
From: Jeff Layton @ 2017-10-06 10:37 UTC (permalink / raw
To: Aurelien Aptel, linux-cifs-u79uwXL29TY76Z2rM5mHXA
Cc: smfrench-Re5JQEeQqe8AvxtiuMwx3w
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>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v2] man: generate all man pages from POD files when buidling
[not found] ` <20170929140303.24880-1-aaptel-IBi9RG/b67k@public.gmane.org>
2017-10-06 10:37 ` [PATCH v2] " Jeff Layton
@ 2017-10-23 12:31 ` Jeff Layton
[not found] ` <1508761900.5859.10.camel-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>
1 sibling, 1 reply; 4+ messages in thread
From: Jeff Layton @ 2017-10-23 12:31 UTC (permalink / raw
To: Aurelien Aptel
Cc: smfrench-Re5JQEeQqe8AvxtiuMwx3w, Pavel Shilovskiy,
linux-cifs-u79uwXL29TY76Z2rM5mHXA
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>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v2] man: generate all man pages from POD files when buidling
[not found] ` <1508761900.5859.10.camel-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>
@ 2017-10-23 14:23 ` Aurélien Aptel
0 siblings, 0 replies; 4+ messages in thread
From: Aurélien Aptel @ 2017-10-23 14:23 UTC (permalink / raw
To: Jeff Layton
Cc: smfrench-Re5JQEeQqe8AvxtiuMwx3w, Pavel Shilovskiy,
linux-cifs-u79uwXL29TY76Z2rM5mHXA
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)
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2017-10-23 14:23 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <20170920222053.7977-1-aaptel@suse.com>
[not found] ` <1506431475.3182.4.camel@samba.org>
[not found] ` <1506431475.3182.4.camel-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>
2017-09-26 14:50 ` [PATCH] man: generate all man pages from POD files when buidling Aurélien Aptel
[not found] ` <20170929140303.24880-1-aaptel@suse.com>
[not found] ` <20170929140303.24880-1-aaptel-IBi9RG/b67k@public.gmane.org>
2017-10-06 10:37 ` [PATCH v2] " Jeff Layton
2017-10-23 12:31 ` Jeff Layton
[not found] ` <1508761900.5859.10.camel-eUNUBHrolfbYtjvyW6yDsg@public.gmane.org>
2017-10-23 14:23 ` Aurélien Aptel
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.