Presenting Repodoc. QA checker for Gentoo Docs.

Hi guys:

Like some of you already know, I'm (sometimes) working on a tool to make 
some sanity checks to our docs before committing them.

I wrote a little (and dirty) prototype which was tested by some gdp 
members and other people working on Gentoo docs. It was version 
0.1_alpha. Now, and mostly thanks to ferdy's help coding bash, is a 
pleasure announce that, a new and very improved version is ready: 0.1_beta

General Info about repodoc, what exactly is, features, installation and 
usage can be found at:
  http://dev.gentoo.org/~yoswink/repodoc/

Info about changes from 0.1_alpha to 0.1_beta:
  http://dev.gentoo.org/~yoswink/repodoc/ChangeLog.txt

Ebuild is ready at:
  http://dev.gentoo.org/~yoswink/repodoc/ebuilds/repodoc-0.1_beta.ebuild

Bugs, flames, feedback or ideas are always welcome.

P.D: If you are Google and want to buy another nice beta version 
application, I'm sure we can talk about the prize ;)

P.D2: No, it won't cut any of your fingers (yet).

------------------------
José Luis Rivero <yoswink <at> gentoo.org>
Gentoo Doc / Gentoo Doc-es / Gentoo-alpha

Larry the Cow -

Hi guys,

 

Does anybody know where can I get this image - http://www.gentoo.org/images/poster.jpg - without English text?

It's a bit boring to redraw that from scratch to put Russian text there.

 

WKR,

Alex Chumakov

Gentoo Best Practices

marienz pointed out on #gentoo that there's not much documentation on Gentoo 
Best Practices. I started to think about what this means.

In General:
I guess "Best Practices" would be stuff that most people already know how to 
do, but do in different ways. There are more and less "Gentoo-like" ways of 
doing things. Of course, the docs team may already have a definition for 
"Gentoo-like", but I suggest it means a more maintainable or more flexible method.

More Specifically:
I'm trying to generalize "best practices" here, but first let me get us on the 
same page by being specific. The topic in question on #gentoo was keyword 
unmasking. Besides the portage man page and some brief pointers on the wiki, 
there's not a lot of documentation on the syntax of package.keywords. There are 
better and worse ways to go about unmasking. One of the worst ways is to use 
ACCEPT_KEYWORDS. It's difficult to maintain (maximizes your chance of hitting a 
broken package *or* dep), nearly impossible to reverse, and fairly inflexible 
in configuration, because it treats every package the same.

A better way might to use the tilde-version method of keywording for explicitly 
installed packages, and the plain atom method for keyword-masked dependencies 
not explicitly in the world file. This method would be flexible (done on a 
package-by-package basis, with individual dependency control), maintainable (if 
the explicitly-installed package's stable version is higher than the version 
number in package.keywords, then the stable version is used, and the 
dependencies' versions still go no higher than expressed in the explicitly 
installed package's ebuild), and reversible.

The Point:
It's fine if you disagree with that particular suggestion for a best practice 
the point of this email is to suggest that there ought to be some documentation 
of best practices. So far the docs team has done a great job of demonstrating 
how to get things done. The best practices doc could answer those of us who, on 
occasion wonder *why* we do things a certain way.

What do you think?
-Mike
--

-- 
gentoo-doc <at> gentoo.org mailing list

Re: Larry the Cow -

achumakov <at> gentoo.org wrote:
> Hi guys,
>  
> Does anybody know where can I get this image -
> http://www.gentoo.org/images/poster.jpg - without English text?
> It's a bit boring to redraw that from scratch  to put Russian text there.
>  
> WKR,
> Alex Chumakov

The original author of that image is no longer with Gentoo. We do not
have a copy of the originals, sorry.

Re: Larry the Cow -

I removed the text and cleaned it up a bit:

http://www.dnbrown.net/poster.png

-Eric

On 4/4/06, Curtis Napier <curtis119 <at> gentoo.org> wrote:
> achumakov <at> gentoo.org wrote:
> > Hi guys,
> >
> > Does anybody know where can I get this image -
> > http://www.gentoo.org/images/poster.jpg - without English text?
> > It's a bit boring to redraw that from scratch  to put Russian text there.
> >
> > WKR,
> > Alex Chumakov
>
> The original author of that image is no longer with Gentoo. We do not
> have a copy of the originals, sorry.
>
>
>
>

--

-- 
gentoo-doc <at> gentoo.org mailing list

Re: Larry the Cow -

Hey, that looks pretty nice. Good work! :)

Eric Brown wrote:
> I removed the text and cleaned it up a bit:
> 
> http://www.dnbrown.net/poster.png
> 
> 
> -Eric
> 
> 
> On 4/4/06, Curtis Napier <curtis119 <at> gentoo.org> wrote:
> 
>>achumakov <at> gentoo.org wrote:
>>
>>>Hi guys,
>>>
>>>Does anybody know where can I get this image -
>>>http://www.gentoo.org/images/poster.jpg - without English text?
>>>It's a bit boring to redraw that from scratch  to put Russian text there.
>>>
>>>WKR,
>>>Alex Chumakov
>>
>>The original author of that image is no longer with Gentoo. We do not
>>have a copy of the originals, sorry.
>>
>>
>>
>>
> 
> 

RE: Larry the Cow -

Thank you Eric!

Soon you'll be able to see it in funny Cyrillic! 

-Alex

-----Original Message-----
From: Eric Brown [mailto:airuike <at> gmail.com] 
Sent: Wednesday, April 05, 2006 5:04 AM
To: gentoo-doc <at> lists.gentoo.org
Subject: Re: [gentoo-doc] Larry the Cow -

I removed the text and cleaned it up a bit:

http://www.dnbrown.net/poster.png

-Eric

On 4/4/06, Curtis Napier <curtis119 <at> gentoo.org> wrote:
> achumakov <at> gentoo.org wrote:
> > Hi guys,
> >
> > Does anybody know where can I get this image - 
> > http://www.gentoo.org/images/poster.jpg - without English text?
> > It's a bit boring to redraw that from scratch  to put Russian text
there.
> >
> > WKR,
> > Alex Chumakov
>
> The original author of that image is no longer with Gentoo. We do not 
> have a copy of the originals, sorry.
>
>
>
>

--
gentoo-doc <at> gentoo.org mailing list

--

-- 
gentoo-doc <at> gentoo.org mailing list

http://www.gentoo.org/main/en/articles.xml

Brandon Grace wrote:
> curtis,
>     while trying to go to the links for the LPI i found they are out of
>     date.  IBM has a new link for all the LPI materiæl.
>     http://www-128.ibm.com/developerworks/linux/lpi/
>     http://www-128.ibm.com/developerworks/linux/lpi/101.html
>     http://www-128.ibm.com/developerworks/linux/lpi/102.html
> 
> brandon aka c0ns0le-[wk-hm]
> 

Thanks for submitting this. Those document links are maintained by the
GDP and I've forwarded this email to them.

--curtis

Link to docs in ebuilds

Hello All,
I was just wondering if this has been thought of before -- a lot of
ebuilds have a guide that should be read before/after installation.
For example, anybody emerge'ing bluez will probably want to read the
Gentoo Bluetooth Guide. Does it make sense to do something like this,
then:

1) add a RELATED_DOC variable to ebuilds to point to the related documentation
2) Before/after the first install the user is given an einfo message
about the doc
3) I don't know how easy this is, but we can possibly set up some way
in which the user can be notified if the doc changes as well. This
could either be done by looking up the doc online each time, or
putting some more metadata into the ebuild.

Thoughts?
--
Arun Raghavan
(http://nemesis.accosted.net)
v2sw5Chw4+5ln4pr6$OFck2ma4+9u8w3+1!m?l7+9GSCKi056
e6+9i4b8/9HTAen4+5g4/8APa2Xs8r1/2p5-8 hackerkey.com

--

-- 
gentoo-doc <at> gentoo.org mailing list

Re: Link to docs in ebuilds

Most ebuilds that have docs on gentoo.org already have einfo notices pointing
users to read the appropriate docs at their various locations.

Really, though, if you're wanting a new Portage feature (RELATED_DOC or some
other ebuild variable), your best bet is to ask on the portage or gentoo-dev
mailing lists and/or the appropriate IRC channels.

Realistically, though, it's impossible to automatically notify users when a doc
changes.

Arun Raghavan wrote:
> Hello All,
> I was just wondering if this has been thought of before -- a lot of
> ebuilds have a guide that should be read before/after installation.
> For example, anybody emerge'ing bluez will probably want to read the
> Gentoo Bluetooth Guide. Does it make sense to do something like this,
> then:
> 
> 1) add a RELATED_DOC variable to ebuilds to point to the related documentation
> 2) Before/after the first install the user is given an einfo message
> about the doc
> 3) I don't know how easy this is, but we can possibly set up some way
> in which the user can be notified if the doc changes as well. This
> could either be done by looking up the doc online each time, or
> putting some more metadata into the ebuild.
> 
> Thoughts?
> --
> Arun Raghavan
> (http://nemesis.accosted.net)
> v2sw5Chw4+5ln4pr6$OFck2ma4+9u8w3+1!m?l7+9GSCKi056
> e6+9i4b8/9HTAen4+5g4/8APa2Xs8r1/2p5-8 hackerkey.com
>