Migrating man page to asciidoc?
 

Hello!


According to git blame, the man page of catalyst hasn't been touched
since 2005. I would like to migrate it to Asciidoc to ease up future
maintenance. I would add a Makefile including a "dist" target to make
sure we always ship releases with an updated man page. The list of
supported subarches could be pulled into the man page automatically.

What do you say?

Best,



Sebastian

Migrating man page to asciidoc?
 

В Птн, 24/06/2011 в 02:41 +0200, Sebastian Pipping пишет:
> According to git blame, the man page of catalyst hasn't been touched
> since 2005. I would like to migrate it to Asciidoc to ease up future
> maintenance. I would add a Makefile including a "dist" target to make
> sure we always ship releases with an updated man page. The list of
> supported subarches could be pulled into the man page automatically.
>
> What do you say?

For me if man page was not touched since 2005 means that it's completely
unmaintained and thus since you are interested in maintaining - just go
ahead!

BTW, thanks for your efforts.

--
Peter.

Migrating man page to asciidoc?
 

Hello!


Migration done:
- Man page source now asciidoc
- List of subarches generated and included
- Makefile added, targets:
- all
- dist
- clean

http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commitdiff;h=fa940f755fbe539ffdeed7 48df7f1e31d9427f72

Best,



Sebastian

Migrating man page to asciidoc?
 

On Fri, Jun 24, 2011 at 1:16 PM, Sebastian Pipping <sping@gentoo.org> wrote:
> Hello!
>
>
> Migration done:
> - Man page source now asciidoc
> - List of subarches generated and included
> - Makefile added, targets:
> *- all
> *- dist
> *- clean
>
> http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commitdiff;h=fa940f755fbe539ffdeed7 48df7f1e31d9427f72
>
> Best,
>
>
>
> Sebastian

I see that you've committed these changes to only the catalyst_2
branch, and not master. Will you commit them to master as well?

Matt

Migrating man page to asciidoc?
 

On 06/25/2011 07:30 PM, Matt Turner wrote:
> I see that you've committed these changes to only the catalyst_2
> branch, and not master. Will you commit them to master as well?

Yes, in a minute.


While we're at keeping things in sync: have you propagated your updates
to the list of subarches to the web page? After running "make" you can
find updated GuideXML for copy-n-paste at ./doc/subarches.generated.xml.
Admittedly, this change would be easy (or easier?) to do incrementally.

Best,



Sebastian

Migrating man page to asciidoc?
 

On Sat, Jun 25, 2011 at 1:50 PM, Sebastian Pipping <sping@gentoo.org> wrote:
> While we're at keeping things in sync: have you propagated your updates
> to the list of subarches to the web page? *After running "make" you can
> find updated GuideXML for copy-n-paste at ./doc/subarches.generated.xml.
> *Admittedly, this change would be easy (or easier?) to do incrementally.

Just updated. Thanks for the python script. :)

Matt

Migrating man page to asciidoc?
 

On Sat, Jun 25, 2011 at 1:50 PM, Sebastian Pipping <sping@gentoo.org> wrote:
> On 06/25/2011 07:30 PM, Matt Turner wrote:
>> I see that you've committed these changes to only the catalyst_2
>> branch, and not master. Will you commit them to master as well?
>
> Yes, in a minute.

I get this when trying to do `EGIT_BRANCH="catalyst_2" emerge
=catalyst-9999` I suppose because asciidoc isn't listed as a
dependency.

./doc/make_subarch_table_guidexml.py
a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=`fgrep
'__version__=' catalyst | sed 's|^__version__="(.*)"$|1|'`"
--format=manpage -D files "doc/catalyst.1.txt"
/bin/sh: a2x: command not found
make: *** [files/catalyst.1] Error 127
emake failed

but I see that asciidoc has quite a number of dependencies.

[ebuild N ] media-libs/jpeg-8c USE="-static-libs"
[ebuild N ] app-text/build-docbook-catalog-1.6
[ebuild N ] media-libs/libpng-1.4.7 USE="-apng -static-libs"
[ebuild N ] virtual/jpeg-0 USE="-static-libs"
[ebuild N ] dev-libs/libgpg-error-1.10 USE="nls -common-lisp
-static-libs"
[ebuild N ] app-text/sgml-common-0.6.3-r5
[ebuild N ] dev-lang/swig-2.0.4 USE="pcre -ccache -doc"
[ebuild N ] dev-util/gtk-doc-am-1.17
[ebuild N ] app-text/docbook-xsl-stylesheets-1.76.1
[ebuild N ] dev-libs/libgcrypt-1.5.0_beta1-r2 USE="-static-libs"
[ebuild N ] media-libs/gd-2.0.35-r3 USE="fontconfig jpeg png
truetype zlib -static-libs -xpm"
[ebuild N ] dev-libs/glib-2.28.8 USE="static-libs -debug -doc
-fam (-introspection) (-selinux) -test -xattr"
[ebuild N ] media-gfx/graphviz-2.26.3-r3 USE="nls perl python
-cairo -doc -examples -gtk (-java) -lasi -ruby -static-libs -tcl"
[ebuild N ] app-text/docbook-xml-dtd-4.5-r1
[ebuild N ] dev-libs/libxslt-1.1.26-r1 USE="crypt python -debug"
[ebuild N ] app-text/asciidoc-8.6.5 USE="-examples -highlight
-test -vim-syntax"

Is there some way we can slim this down? Presumably asciidoc isn't
going to be using any image-related programs for generating a man
page.

Matt

Migrating man page to asciidoc?
 

On 06/26/2011 04:02 AM, Matt Turner wrote:
> I get this when trying to do `EGIT_BRANCH="catalyst_2" emerge
> =catalyst-9999` I suppose because asciidoc isn't listed as a
> dependency.
>
> ./doc/make_subarch_table_guidexml.py
> a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=`fgrep
> '__version__=' catalyst | sed 's|^__version__="(.*)"$|1|'`"
> --format=manpage -D files "doc/catalyst.1.txt"
> /bin/sh: a2x: command not found
> make: *** [files/catalyst.1] Error 127
> emake failed

Correct, asciidoc is missing.


> but I see that asciidoc has quite a number of dependencies.
>
> [ebuild N ] media-libs/jpeg-8c USE="-static-libs"
> [ebuild N ] app-text/build-docbook-catalog-1.6
> [ebuild N ] media-libs/libpng-1.4.7 USE="-apng -static-libs"
> [ebuild N ] virtual/jpeg-0 USE="-static-libs"
> [ebuild N ] dev-libs/libgpg-error-1.10 USE="nls -common-lisp
> -static-libs"
> [ebuild N ] app-text/sgml-common-0.6.3-r5
> [ebuild N ] dev-lang/swig-2.0.4 USE="pcre -ccache -doc"
> [ebuild N ] dev-util/gtk-doc-am-1.17
> [ebuild N ] app-text/docbook-xsl-stylesheets-1.76.1
> [ebuild N ] dev-libs/libgcrypt-1.5.0_beta1-r2 USE="-static-libs"
> [ebuild N ] media-libs/gd-2.0.35-r3 USE="fontconfig jpeg png
> truetype zlib -static-libs -xpm"
> [ebuild N ] dev-libs/glib-2.28.8 USE="static-libs -debug -doc
> -fam (-introspection) (-selinux) -test -xattr"
> [ebuild N ] media-gfx/graphviz-2.26.3-r3 USE="nls perl python
> -cairo -doc -examples -gtk (-java) -lasi -ruby -static-libs -tcl"
> [ebuild N ] app-text/docbook-xml-dtd-4.5-r1
> [ebuild N ] dev-libs/libxslt-1.1.26-r1 USE="crypt python -debug"
> [ebuild N ] app-text/asciidoc-8.6.5 USE="-examples -highlight
> -test -vim-syntax"
>
> Is there some way we can slim this down? Presumably asciidoc isn't
> going to be using any image-related programs for generating a man
> page.

The image stuff is indirect dependencies, see --tree.

Future releases of catalyst do not have this problem as the make file
comes pre-rendered with the tarball. This is a live-ebuild issue.

Best,



Sebastian

Migrating man page to asciidoc?
 

On Sun, Jun 26, 2011 at 04:36:15AM +0200, Sebastian Pipping wrote:
> On 06/26/2011 04:02 AM, Matt Turner wrote:
> > I get this when trying to do `EGIT_BRANCH="catalyst_2" emerge
> > =catalyst-9999` I suppose because asciidoc isn't listed as a
> > dependency.
> >
> > ./doc/make_subarch_table_guidexml.py
> > a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=`fgrep
> > '__version__=' catalyst | sed 's|^__version__="(.*)"$|1|'`"
> > --format=manpage -D files "doc/catalyst.1.txt"
> > /bin/sh: a2x: command not found
> > make: *** [files/catalyst.1] Error 127
> > emake failed
>
> Correct, asciidoc is missing.
>
>
> > but I see that asciidoc has quite a number of dependencies.
> >
> > [ebuild N ] media-libs/jpeg-8c USE="-static-libs"
> > [ebuild N ] app-text/build-docbook-catalog-1.6
> > [ebuild N ] media-libs/libpng-1.4.7 USE="-apng -static-libs"
> > [ebuild N ] virtual/jpeg-0 USE="-static-libs"
> > [ebuild N ] dev-libs/libgpg-error-1.10 USE="nls -common-lisp
> > -static-libs"
> > [ebuild N ] app-text/sgml-common-0.6.3-r5
> > [ebuild N ] dev-lang/swig-2.0.4 USE="pcre -ccache -doc"
> > [ebuild N ] dev-util/gtk-doc-am-1.17
> > [ebuild N ] app-text/docbook-xsl-stylesheets-1.76.1
> > [ebuild N ] dev-libs/libgcrypt-1.5.0_beta1-r2 USE="-static-libs"
> > [ebuild N ] media-libs/gd-2.0.35-r3 USE="fontconfig jpeg png
> > truetype zlib -static-libs -xpm"
> > [ebuild N ] dev-libs/glib-2.28.8 USE="static-libs -debug -doc
> > -fam (-introspection) (-selinux) -test -xattr"
> > [ebuild N ] media-gfx/graphviz-2.26.3-r3 USE="nls perl python
> > -cairo -doc -examples -gtk (-java) -lasi -ruby -static-libs -tcl"
> > [ebuild N ] app-text/docbook-xml-dtd-4.5-r1
> > [ebuild N ] dev-libs/libxslt-1.1.26-r1 USE="crypt python -debug"
> > [ebuild N ] app-text/asciidoc-8.6.5 USE="-examples -highlight
> > -test -vim-syntax"
> >
> > Is there some way we can slim this down? Presumably asciidoc isn't
> > going to be using any image-related programs for generating a man
> > page.
>
> The image stuff is indirect dependencies, see --tree.
>
> Future releases of catalyst do not have this problem as the make file
> comes pre-rendered with the tarball. This is a live-ebuild issue.

No, we can't have the manpage pre-rendered in the tarball, because that
makes the tarball different every time it is created since the
date/timestamps in the archive will be different. In other words, it is
not possible for anyone to ever reproduce the exact same tarball that we
produce.

I see two ways around this: We can either make asciidoc a build time
dependency so that the user can use something like "make manpage" to
generate the manpage or we can go back to the manpage that is in the git
repository.

Thoughts?

William

Migrating man page to asciidoc?
 

On 06/26/2011 04:49 AM, William Hubbs wrote:
> No, we can't have the manpage pre-rendered in the tarball, because that
> makes the tarball different every time it is created since the
> date/timestamps in the archive will be different. In other words, it is
> not possible for anyone to ever reproduce the exact same tarball that we
> produce.

The varience in timestamp has been no problem for other projects
including genkernel. If all that varies is the time stamp and it
matters to you, it would be easy to add a section to the Makefile
setting the timestamp to a hardcoded value.


> I see two ways around this: We can either make asciidoc a build time
> dependency so that the user can use something like "make manpage" to
> generate the manpage

That adds quite some load on indirect dependencies for more or less
nothing, as seen with Matt earlier.


> or we can go back to the manpage that is in the git
> repository.

Do I have to list reasons against this option?

Best,




Sebastian