FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Gentoo > Gentoo Catalyst

 
 
LinkBack Thread Tools
 
Old 06-26-2011, 03:36 AM
William Hubbs
 
Default Migrating man page to asciidoc?

On Sun, Jun 26, 2011 at 05:14:38AM +0200, Sebastian Pipping wrote:
> 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.

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

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

William
 
Old 06-26-2011, 03:46 AM
William Hubbs
 
Default Migrating man page to asciidoc?

I need to appologise for the last comment I made in my previous message
about you not discussing this issue. I see that you did mention it, but
it was before I came on board.

http://archives.gentoo.org/gentoo-catalyst/msg_78cd6eae401bfa7a499418bc6cbc225e.xml

I hope you will accept my appology.

However, I would still like to know why this conversion was needed; all
we had to do was update the manpage. The conversion does make it more
difficult for us to generate reproducable tarballs, which means that for
gentoo's qa policy someone always has to keep the tarball we use in
their dev space and we have to point to that tarball with SRC_URI.

But, that would not be necessary if we generate the tarball from the git
repo e.g. the way openrc does.

William
 
Old 06-26-2011, 03:49 AM
Sebastian Pipping
 
Default Migrating man page to asciidoc?

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.


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


>>> 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.
Plus Asciidoc syntax is more readable.

- Man page keeps itself in sync on

- list of subarches

- version of catalyst

- Option to make XHTML from the same source

Best,



Sebastian
 
Old 06-26-2011, 03:59 AM
Sebastian Pipping
 
Default Migrating man page to asciidoc?

On 06/26/2011 05:46 AM, William Hubbs wrote:
> I need to appologise for the last comment I made in my previous message
> about you not discussing this issue. I see that you did mention it, but
> it was before I came on board.
>
> http://archives.gentoo.org/gentoo-catalyst/msg_78cd6eae401bfa7a499418bc6cbc225e.xml
>
> I hope you will accept my appology.

Yes, no problem.


> However, I would still like to know why this conversion was needed;

To increase the fun maintaining it for present and future.
Run "make && man ./files/catalyst.1" to see how much better it looks now
than a few days ago. I wouldn't have spent time on improving it at
*roff level.


> all
> we had to do was update the manpage. The conversion does make it more
> difficult for us to generate reproducable tarballs, which means that for
> gentoo's qa policy someone always has to keep the tarball we use in
> their dev space and we have to point to that tarball with SRC_URI.

I'm not following. We have to keep the tarball on mirrors anyway. Not?

No generated files means maintaining some things at several places.
Without the generator, mips2 and mipsel2 would still be listed on
catalyst's webpage.


> But, that would not be necessary if we generate the tarball from the git
> repo e.g. the way openrc does.

Alright. I don't want to limit myself to a static man page (or live
with generated files under version control).

Best,



Sebastian
 
Old 06-26-2011, 04:10 AM
Matt Turner
 
Default Migrating man page to asciidoc?

On Sat, Jun 25, 2011 at 11:14 PM, Sebastian Pipping <sping@gentoo.org> wrote:
> 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.

For the live ebuild, I don't see any problem with this. I think we
just want to avoid having to install asciidoc for the released
catalyst versions.

>> or we can go back to the manpage that is in the git
>> repository.
>
> Do I have to list reasons against this option?

Yeah, this option is really distasteful.

I think the best solution is to simply hack the timestamp on the
generated files or something similar. We definitely don't want `emerge
=catalyst-2*` to require asciidoc and all its indirect dependencies
for a single man page, and we definitely don't want to check-in
generated files to git for a variety of reasons.

Matt
 
Old 06-26-2011, 04:14 AM
Sebastian Pipping
 
Default Migrating man page to asciidoc?

On 06/26/2011 06:10 AM, Matt Turner wrote:
> For the live ebuild, I don't see any problem with this. I think we
> just want to avoid having to install asciidoc for the released
> catalyst versions.

The tarballs are coming with a rendered man page - it is generated on
the machine running "make dist", not the machine installing catalyst.


>> Do I have to list reasons against this option?
>
> Yeah, this option is really distasteful.

Thanks.


> I think the best solution is to simply hack the timestamp on the
> generated files or something similar. We definitely don't want `emerge
> =catalyst-2*` to require asciidoc and all its indirect dependencies
> for a single man page, and we definitely don't want to check-in
> generated files to git for a variety of reasons.

Again, see above.

Best,



Sebastian
 
Old 06-26-2011, 04:33 AM
William Hubbs
 
Default Migrating man page to asciidoc?

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
 
Old 06-26-2011, 04:44 AM
William Hubbs
 
Default Migrating man page to asciidoc?

On Sun, Jun 26, 2011 at 06:14:59AM +0200, Sebastian Pipping wrote:
> > I think the best solution is to simply hack the timestamp on the
> > generated files or something similar. We definitely don't want `emerge
> > =catalyst-2*` to require asciidoc and all its indirect dependencies
> > for a single man page, and we definitely don't want to check-in
> > generated files to git for a variety of reasons.

The thing about this approach though is, how do you know what timestamp
to put on the generated files?

When you do:

git archive --prefix catalyst-x.x -o catalyst-x.x.tar catalyst_x_x

It takes the time/date from the tree some way and puts that time and
date on the files in the tarball.

William
 
Old 06-26-2011, 04:46 AM
Sebastian Pipping
 
Default Migrating man page to asciidoc?

On 06/26/2011 06:44 AM, William Hubbs wrote:
> On Sun, Jun 26, 2011 at 06:14:59AM +0200, Sebastian Pipping wrote:
>>> I think the best solution is to simply hack the timestamp on the
>>> generated files or something similar. We definitely don't want `emerge
>>> =catalyst-2*` to require asciidoc and all its indirect dependencies
>>> for a single man page, and we definitely don't want to check-in
>>> generated files to git for a variety of reasons.
>
> The thing about this approach though is, how do you know what timestamp
> to put on the generated files?

You could pick a hardcode one. If traball identity is the goal, any
fake timestamp will suffice.


> When you do:
>
> git archive --prefix catalyst-x.x -o catalyst-x.x.tar catalyst_x_x
>
> It takes the time/date from the tree some way and puts that time and
> date on the files in the tarball.

I'm aware. I use git archive where I don't have generated content involved.



Sebastian
 
Old 06-26-2011, 04:57 AM
Sebastian Pipping
 
Default Migrating man page to asciidoc?

On 06/26/2011 06:33 AM, William Hubbs wrote:
> 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.

Frankly, I don't care about that feature. I care about content and Git
tags that lead to content.


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

I was trying to say that you get quite something for the cost you put
into dependencies. You save re-writing things yourself and you get more
features for free. That's what the cost is for.


>> Plus Asciidoc syntax is more readable.
>
> You can use man ./catalyst.1 to read the man page.

Are you serious? I want syntax to be readable while editing, not after
pre-processing. With that argument we could be writing man pages in
assembly.

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

Again, i don't care.


> * 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.

I disagree on bloat and on little gain.

If you insist on changing status quo I would like to call in a vote.

Best,



Sebastian
 

Thread Tools




All times are GMT. The time now is 01:31 PM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org