[gentoo-dev] added Gentoo-HOWTO

[gentoo-dev] added Gentoo-HOWTO

[Pete Gavin]

Hi,

I've gotten a decent start on my Gentoo-HOWTO. I put it in the root of
the portage tree, and its called Gentoo-HOWTO. Please read it and give
me any comments on things you think I should change/add/subtract/etc.

Thanx
Pete

Re: [gentoo-dev] added Gentoo-HOWTO

[drobbins]

On Wed, Feb 21, 2001 at 01:36:05PM -0700, Pete Gavin wrote:
> Hi,
> 
> I've gotten a decent start on my Gentoo-HOWTO. I put it in the root of
> the portage tree, and its called Gentoo-HOWTO. Please read it and give
> me any comments on things you think I should change/add/subtract/etc.

This looks really good.  I will make little fixes here and there when I
have time; in the mean time, please continue adding to it.  Also, when
it gets a bit more developed (and I get a bit more time), I'll convert
it to our new XML doc format and get it on our web site.

Best Regards,

-- 
Daniel Robbins					<drobbins@gentoo.org>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.			

Re: [gentoo-dev] added Gentoo-HOWTO

[Achim Gottinger]

Pete Gavin wrote:
> 
> Hi,
> 
> I've gotten a decent start on my Gentoo-HOWTO. I put it in the root of
> the portage tree, and its called Gentoo-HOWTO. Please read it and give
> me any comments on things you think I should change/add/subtract/etc.
> 
> Thanx
> Pete

Hi Pete,

I took a short look at your HOWTO and think it sounds good.

Comments:

sys-build is no longer used instead the packages listed in
current-packages.build are used together with the USE flags
"build" and "build-static".

I don't think it is neccesary to add -gentoo to our patches.
Sometimes it is better to store patches without the ${PV} because
the same patch can be used for different versions.
Sometimes it is better to store patches in files/${PV} to keep the list 
in files small.


How about creating a new package in app-doc and place the Gentoo-HOWTO 
in there.

I want to make a doc for the USE variables and this can be placed there
too.

Daniel,

What do you think about using docbook for these docs. The sgml-tools
should work quite well and we can produce the following output formates:
dvi html man pdf ps rtf tex texi txt.
We can add our own html-backend or an xml backend that can be used
for xslt transformation.

achim~


> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] added Gentoo-HOWTO

[drobbins]

On Thu, Feb 22, 2001 at 06:03:52PM +0100, Achim Gottinger wrote:

> Daniel,

> What do you think about using docbook for these docs. The sgml-tools should
> work quite well and we can produce the following output formates: dvi html
> man pdf ps rtf tex texi txt.  We can add our own html-backend or an xml
> backend that can be used for xslt transformation.

Well, I'm not too familiar with the docbook syntax, but I took a quick look at
a sample docbook SGML document and I'm afraid that it would require a monstrous
amount of custom XSLT to get into the format that we want.

I agree that having a unified doc format that can generate man pages as well as
web documents is what we need.  Part of me thinks that it may be easier to
create our own man page conversion XSLT than it would be to create our web page
conversion docbook XSLT.

If I am going to be doing most of the documentation, then I'll most likely go
with a custom XML format.  If someone else wants to invest some time getting
our docs into docbook format (and handling the web page conversion issues),
then maybe we can go in that direction.

-- 
Daniel Robbins					<drobbins@gentoo.org>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.			

Re: [gentoo-dev] added Gentoo-HOWTO

[drobbins]

Well,

One advantage to using docbook is that once we get the docbook xml/sgml -> html
conversion working well (so that it integrates into our website), we should be
able to offer most of the Linux HOWTOs direct from gentoo.org.

-- 
Daniel Robbins					<drobbins@gentoo.org>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.			

Re: [gentoo-dev] added Gentoo-HOWTO

[Achim Gottinger]

drobbins@gentoo.org wrote:
> 
> Well,
> 
> One advantage to using docbook is that once we get the docbook xml/sgml -> html
> conversion working well (so that it integrates into our website), we should be
> able to offer most of the Linux HOWTOs direct from gentoo.org.
> 

Well I think XSLT(sablotron) is the right choice for our webpage.

I'm willing to make a docbook backend that creates an xml we can use on
our webpage.

I'm getting stupid over here doing nothing else then rewoking and
testing
packages since a few weeks. ;~}

I don't think we should make a extra html backend. It's better to
produce
an XML output that can be processed with our webpages XSLT.
Otherwise we must allways change both.


I have now idea how comlex this will be. But I think writing new
backends
for docbook is well documented. I will take a look at it.

Unfortunately I can't find the XSLT-stuff you did. Can you please resend
me that stuff.

achim~

> --
> Daniel Robbins                                  <drobbins@gentoo.org>
> President/CEO                                   http://www.gentoo.org
> Gentoo Technologies, Inc.
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] added Gentoo-HOWTO

[drobbins]

On Thu, Feb 22, 2001 at 06:54:06PM +0100, Achim Gottinger wrote:

> Unfortunately I can't find the XSLT-stuff you did. Can you please resend me
> that stuff.

I added it to Portage -- /usr/portage/app-doc/gentoo-doc/files. :)

-- 
Daniel Robbins					<drobbins@gentoo.org>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.			

Re: [gentoo-dev] added Gentoo-HOWTO

[Pete Gavin]

On Thu, Feb 22, 2001 at 06:03:52PM +0100, Achim Gottinger wrote:
> sys-build is no longer used instead the packages listed in
> current-packages.build are used together with the USE flags
> "build" and "build-static".

Ok, I've removed the reference to sys-build.

> 
> I don't think it is neccesary to add -gentoo to our patches.
> Sometimes it is better to store patches without the ${PV} because
> the same patch can be used for different versions.
> Sometimes it is better to store patches in files/${PV} to keep the list 
> in files small.

Hmm... Yeah, I guess the -gentoo isn't entirely necessary, but in
certain cases, like when we update a kernel to a new version by using
a patch (which would simply be called something like linux-2.4.1.diff)
it *would* be necessary, and always using -gentoo would let others
know that the diff contains *our* modifications to the source tree,
instead of modifications we got somewhere else. And yes, if we have
alot of files that go with an ebuild, we should put them in
files/${PV}. I'll add that in to the howto. I think, though, that
patches should not be used between multiple versions of an ebuild,
because if they were, any changes/fixes that are made in the patch
would automatically be back-ported to previous versions of the
package. This totally defeats the purpose of having multiple revisions
of a package.

> 
> 
> How about creating a new package in app-doc and place the Gentoo-HOWTO 
> in there.
> 
> I want to make a doc for the USE variables and this can be placed there
> too.
> 
> Daniel,
> 
> What do you think about using docbook for these docs. The sgml-tools
> should work quite well and we can produce the following output formates:
> dvi html man pdf ps rtf tex texi txt.
> We can add our own html-backend or an xml backend that can be used
> for xslt transformation.
> 

I know next to nothing about docbook/sgml/etc. Does anyone know a good
place to start learning about this?

Pete

Re: [gentoo-dev] added Gentoo-HOWTO

[Achim Gottinger]

Pete Gavin wrote:
> 
> On Thu, Feb 22, 2001 at 06:03:52PM +0100, Achim Gottinger wrote:
> > sys-build is no longer used instead the packages listed in
> > current-packages.build are used together with the USE flags
> > "build" and "build-static".
> 
> Ok, I've removed the reference to sys-build.
> 
> >
> > I don't think it is neccesary to add -gentoo to our patches.
> > Sometimes it is better to store patches without the ${PV} because
> > the same patch can be used for different versions.
> > Sometimes it is better to store patches in files/${PV} to keep the list
> > in files small.
> 
> Hmm... Yeah, I guess the -gentoo isn't entirely necessary, but in
> certain cases, like when we update a kernel to a new version by using
> a patch (which would simply be called something like linux-2.4.1.diff)
> it *would* be necessary, and always using -gentoo would let others
> know that the diff contains *our* modifications to the source tree,
> instead of modifications we got somewhere else. And yes, if we have
> alot of files that go with an ebuild, we should put them in
> files/${PV}. I'll add that in to the howto. I think, though, that
> patches should not be used between multiple versions of an ebuild,
> because if they were, any changes/fixes that are made in the patch
> would automatically be back-ported to previous versions of the
> package. This totally defeats the purpose of having multiple revisions
> of a package.
> 
> >
> >
> > How about creating a new package in app-doc and place the Gentoo-HOWTO
> > in there.
> >
> > I want to make a doc for the USE variables and this can be placed there
> > too.
> >
> > Daniel,
> >
> > What do you think about using docbook for these docs. The sgml-tools
> > should work quite well and we can produce the following output formates:
> > dvi html man pdf ps rtf tex texi txt.
> > We can add our own html-backend or an xml backend that can be used
> > for xslt transformation.
> >
> 
> I know next to nothing about docbook/sgml/etc. Does anyone know a good
> place to start learning about this?
> 
> Pete

http://www.linux.org/docs/ldp/howto/HOWTO-HOWTO/

achim~
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] added Gentoo-HOWTO

[Achim Gottinger]

Pete Gavin wrote:
> 
> On Thu, Feb 22, 2001 at 06:03:52PM +0100, Achim Gottinger wrote:
> > sys-build is no longer used instead the packages listed in
> > current-packages.build are used together with the USE flags
> > "build" and "build-static".
> 
> Ok, I've removed the reference to sys-build.
> 
> >
> > I don't think it is neccesary to add -gentoo to our patches.
> > Sometimes it is better to store patches without the ${PV} because
> > the same patch can be used for different versions.
> > Sometimes it is better to store patches in files/${PV} to keep the list
> > in files small.
> 
> Hmm... Yeah, I guess the -gentoo isn't entirely necessary, but in
> certain cases, like when we update a kernel to a new version by using
> a patch (which would simply be called something like linux-2.4.1.diff)
> it *would* be necessary, and always using -gentoo would let others
> know that the diff contains *our* modifications to the source tree,
> instead of modifications we got somewhere else.

An alternative whould be adding a header to our own patches, similar to
the ones we use for the ebuilds, like glibc people do.
Of cause your attempt is more transparent.

 And yes, if we have
> alot of files that go with an ebuild, we should put them in
> files/${PV}. I'll add that in to the howto. I think, though, that
> patches should not be used between multiple versions of an ebuild,
> because if they were, any changes/fixes that are made in the patch
> would automatically be back-ported to previous versions of the
> package. This totally defeats the purpose of having multiple revisions
> of a package.
> 
> >
> >
> > How about creating a new package in app-doc and place the Gentoo-HOWTO
> > in there.
> >
> > I want to make a doc for the USE variables and this can be placed there
> > too.
> >
> > Daniel,
> >
> > What do you think about using docbook for these docs. The sgml-tools
> > should work quite well and we can produce the following output formates:
> > dvi html man pdf ps rtf tex texi txt.
> > We can add our own html-backend or an xml backend that can be used
> > for xslt transformation.
> >
> 
> I know next to nothing about docbook/sgml/etc. Does anyone know a good
> place to start learning about this?
>
 
http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html

achim~
> Pete
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] added Gentoo-HOWTO

[Achim Gottinger]

Pete Gavin wrote:
> 
> On Thu, Feb 22, 2001 at 06:03:52PM +0100, Achim Gottinger wrote:
> > sys-build is no longer used instead the packages listed in
> > current-packages.build are used together with the USE flags
> > "build" and "build-static".
> 
> Ok, I've removed the reference to sys-build.
> 
> >
> > I don't think it is neccesary to add -gentoo to our patches.
> > Sometimes it is better to store patches without the ${PV} because
> > the same patch can be used for different versions.
> > Sometimes it is better to store patches in files/${PV} to keep the list
> > in files small.
> 
> Hmm... Yeah, I guess the -gentoo isn't entirely necessary, but in
> certain cases, like when we update a kernel to a new version by using
> a patch (which would simply be called something like linux-2.4.1.diff)
> it *would* be necessary, and always using -gentoo would let others
> know that the diff contains *our* modifications to the source tree,
> instead of modifications we got somewhere else. And yes, if we have
> alot of files that go with an ebuild, we should put them in
> files/${PV}. I'll add that in to the howto. I think, though, that
> patches should not be used between multiple versions of an ebuild,
> because if they were, any changes/fixes that are made in the patch
> would automatically be back-ported to previous versions of the
> package. This totally defeats the purpose of having multiple revisions
> of a package.
> 
> >
> >
> > How about creating a new package in app-doc and place the Gentoo-HOWTO
> > in there.
> >
> > I want to make a doc for the USE variables and this can be placed there
> > too.
> >
> > Daniel,
> >
> > What do you think about using docbook for these docs. The sgml-tools
> > should work quite well and we can produce the following output formates:
> > dvi html man pdf ps rtf tex texi txt.
> > We can add our own html-backend or an xml backend that can be used
> > for xslt transformation.
> >
> 
> I know next to nothing about docbook/sgml/etc. Does anyone know a good
> place to start learning about this?

If you want to convert a docbook style sgml file to html you must first 
generate a global catalog.

you can do this the following way:

find /usr/share/sgml -name "catalog" -exec install-catalog -a catalog {}
\;

copy that catalog to /usr/share/sgml.

Now you can try 

docbook2html [docbook sgml]

The other backends do not seem to work yet.

If you want to use emacs psgml mode you must export 

SGML_CATALOG_FILES=/usr/share/sgml/catalog

I will make a package for psgml tomorrow. Additionaly I will try to get
the other backends working.

achim~
> 
> Pete
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev