Mailing List Archive: Link to docs in ebuilds

Link to docs in ebuilds

Apr 12, 2006, 11:03 AM

Post #1 of 8 (2546 views)

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@gentoo.org mailing list

Re: Link to docs in ebuilds [ In reply to ]

nightmorph at gentoo

Apr 12, 2006, 12:31 PM

Post #2 of 8 (2502 views)

Permalink

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

iD8DBQFEPVWLrsJQqN81j74RApa7AJ9SuzFVzz+N6k9fyPdTP1F0itIR0gCeIvCJ
YulB/9oPmkBLrm0xJcet/nk=
=s8aG
-----END PGP SIGNATURE-----
--
gentoo-doc@gentoo.org mailing list

Re: Link to docs in ebuilds [ In reply to ]

fox2mike at gentoo

Apr 12, 2006, 8:29 PM

Post #3 of 8 (2508 views)

Permalink

Arun Raghavan wrote:

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

Yeah, Yoswink IIRC had a similar plan quite sometime back. Yoswink,
would you please share the ideas/details? I'll try digging up IRC logs
as well to see if I can come up with anything.

> 1) add a RELATED_DOC variable to ebuilds to point to the related documentation

I'm yet to read through your idea. Will do in a bit.

AFAICS, the docs-team would be fine with this. I think we would need to
work out a good plan, and then take it to the ebuild folks/list/IRC and
see how we can work it out with them.

I'm quite sure if we have a well thought out idea, people will be
willing to think about implementing it.

Regards,

--
Shyam Mani | <fox2mike@gentoo.org>
docs-team | http://gdp.gentoo.org
GPG Key | 0xFDD0E345

Re: Link to docs in ebuilds [ In reply to ]

neysx at gentoo

Apr 13, 2006, 6:36 AM

Post #4 of 8 (2493 views)

Permalink

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

Has already been asked
http://thread.gmane.org/gmane.linux.gentoo.documentation/2395/focus=2397

The short answer is it's a good idea, but not one GDP can do anything about.
The long answer has been discussed on the -dev ML
http://thread.gmane.org/gmane.linux.gentoo.devel/33433

> 2) Before/after the first install the user is given an einfo message
> about the doc

Ebuild writers write ebuilds and many already point to available docs

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

Very unrealistic.
A yet-to-be-released version of viewcvs (now ViewVC) will provide rss feeds
http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/
(See http://viewvc.tigris.org/source/browse/viewvc/trunk/CHANGES?rev=HEAD)

Wkr
--
/ Xavier Neys
\_ Gentoo Documentation Project
/
/\ http://www.gentoo.org/doc/en/

Re: Link to docs in ebuilds [ In reply to ]

yoswink at gentoo

Apr 17, 2006, 6:42 AM

Post #5 of 8 (2503 views)

Permalink

Shyam Mani wrote:
> Arun Raghavan wrote:
>
> [snip]
>
> Yeah, Yoswink IIRC had a similar plan quite sometime back. Yoswink,
> would you please share the ideas/details? I'll try digging up IRC logs
> as well to see if I can come up with anything.
>

( sorry about the delay, I was on holidays :D )

Nah, the main idea was behind improving integration between docs and
ebuilds by replacing "einfo" doc related lines with an own "e-function"
for gdp info. Not sure if this could help in anyway but sure isn't the
solution.

I implemented a stupid mockup [1] but, of course, the problem is bigger
than just this. Please read Xavier's comments on this thread to have a
whole idea about this issue.

Wkr.

-------------------------
Jose Luis Rivero <yoswink @ gentoo .org>
Gentoo/Doc, Gentoo/Alpha

[1] http://dev.gentoo.org/~yoswink/tmp/edoc.png
--
gentoo-doc@gentoo.org mailing list

Re: Link to docs in ebuilds [ In reply to ]

arunisgod at gmail

Apr 17, 2006, 9:00 AM

Post #6 of 8 (2494 views)

Permalink

On 4/17/06, Jose Luis Rivero (YosWinK) <yoswink@gentoo.org> wrote:
> Shyam Mani wrote:
> > Arun Raghavan wrote:
> >
> > [snip]
> >
> > Yeah, Yoswink IIRC had a similar plan quite sometime back. Yoswink,
> > would you please share the ideas/details? I'll try digging up IRC logs
> > as well to see if I can come up with anything.
> >
>
> ( sorry about the delay, I was on holidays :D )
>
> Nah, the main idea was behind improving integration between docs and
> ebuilds by replacing "einfo" doc related lines with an own "e-function"
> for gdp info. Not sure if this could help in anyway but sure isn't the
> solution.

I like the mock-up -- it's what I meant. Basically, what I was saying
is something like this: if the ebuild has a particular variable
(RELATED_DOC, say) defined, the notification message like yours would
be displayed. I tried to see if I could hack this up, but I couldn't
figure out where I could plug it in. I think the change is rather
trivial.

Automatically reflecting updates can wait for another day. :)
--
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@gentoo.org mailing list

Re: Link to docs in ebuilds [ In reply to ]

yoswink at gentoo

Apr 19, 2006, 2:54 AM

Post #7 of 8 (2496 views)

Permalink

Arun Raghavan wrote:
> On 4/17/06, Jose Luis Rivero (YosWinK) <yoswink@gentoo.org> wrote:
>
>>Shyam Mani wrote:
>>
>>>Arun Raghavan wrote:
>>>
>>>[snip]
>>>
>>>Yeah, Yoswink IIRC had a similar plan quite sometime back. Yoswink,
>>>would you please share the ideas/details? I'll try digging up IRC logs
>>>as well to see if I can come up with anything.
>>>
>>
>>( sorry about the delay, I was on holidays :D )
>>
>>Nah, the main idea was behind improving integration between docs and
>>ebuilds by replacing "einfo" doc related lines with an own "e-function"
>>for gdp info. Not sure if this could help in anyway but sure isn't the
>>solution.
>
>
> I like the mock-up -- it's what I meant. Basically, what I was saying
> is something like this: if the ebuild has a particular variable
> (RELATED_DOC, say) defined, the notification message like yours would
> be displayed. I tried to see if I could hack this up, but I couldn't
> figure out where I could plug it in. I think the change is rather
> trivial.
>

I wrote "edoc" function to be used inside ebuilds (same way as einfo,
ewarn, ...) when I made the mock-up. If you want to use it, feel free to
pick up the patch [1] and apply it to /sbin/functions.sh. I just rewrite
the patch few moments ago and it hasn't been tested but shouldn't eat
any of your files :)

The rest of your idea about "particular variable" need to hack emerge,
which is something I really want to avoid.

Wkr,

------------------------------------------------
JosÃ© Luis Rivero <yoswink @ gentoo .org>
Gentoo Doc / Gentoo Alpha

[1] http://dev.gentoo.org/~yoswink/tmp/edoc-funtions.sh.patch
--
gentoo-doc@gentoo.org mailing list

Re: Link to docs in ebuilds [ In reply to ]

arunisgod at gmail

Apr 20, 2006, 11:28 AM

Post #8 of 8 (2500 views)

Permalink

On 4/19/06, Jose Luis Rivero (YosWinK) <yoswink@gentoo.org> wrote:
...
> ewarn, ...) when I made the mock-up. If you want to use it, feel free to
> pick up the patch [1] and apply it to /sbin/functions.sh. I just rewrite

Thanks. Was looking at something like this.

> The rest of your idea about "particular variable" need to hack emerge,
> which is something I really want to avoid.

Te advantage of having this specified as metadata instead of just
printing the message is that it can then be used in any way that we
choose. More flexibility.
--
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@gentoo.org mailing list

Mailing List Archive

Attached Files:

Attached Files: