Re: [gentoo-catalyst] Migrating man page to asciidoc?

[William Hubbs]

On Sun, Jun 26, 2011 at 05:49:17AM +0200, Sebastian Pipping wrote:
> On 06/26/2011 05:36 AM, William Hubbs wrote:
> > That is already done if you use "git archive" to generate the archive
> > and use the tags in the git repository along with that. For an example,
> > look at openrc's git repository.
>
> I'm aware of git archive - it does not support handling of generated
> files afaik.

That's correct, everything has to be in the repository if you use it.
The advantage of doing it that way is that anyone can come along
whenever they want to and generate a tarball that exactly matches the
one we generate at release time. Doing it the other way, they can't.
 
 That is why I think we should make asciidoc an RDEPEND in the ebuilds
 and set up the makefile so that the user generates the content if we
 stick with using asciidoc.

> >>> 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.
> >
> > That is exactly why I prefer the other option I mention below.
>
> Alright.  On the other hand without dependencies you get nowhere: either
> you don#t have features or you build every wheel yourself.
 
 I'm not quite sure what you mean here.

> >>> or we can go back to the manpage that is in the git
> >>> repository.
> >>
> >> Do I have to list reasons against this option?
> >
> > I think it would be helpful if you did since you did the conversion
> > without discussing it with the rest of the team first.
>
> Peter Volkov voted for it, Peter Stuge said the list was rather silent.
>  So I went for it.  The migration in genkernel was of great help.  I see
> your apology in your other mail now, accepting.
>
> Benefits of the current Asciidoc approach:
>
>  - No need to write *roff manually.

I'll give you this one. :-)

>    Plus Asciidoc syntax is more readable.

You can use man ./catalyst.1 to read the man page.

>
>  - Man page keeps itself in sync on
>
>    - list of subarches
>
>    - version of catalyst
>
>  - Option to make XHTML from the same source
 
 The cons of the new approach, as I see it, are:

* auto generated content in tarballs makes it impossible to create the
exact same tarball twice.
* Now we need to have a build time dependency, at least for the live
ebuild, which pulls in about 34mb of downloads just to build the man
page.

Since we are just talking about a man page, imho this is a lot of bloat
for very little gain.

William