After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 91870 - Need a list of what our funky-named packages are
Need a list of what our funky-named packages are
Status: RESOLVED FIXED
Product: website
Classification: Infrastructure
Component: www.gnome.org
current
Other Linux
: Normal normal
: ---
Assigned To: Malcolm Tredinnick
Malcolm Tredinnick
Depends on:
Blocks:
 
 
Reported: 2002-08-28 12:46 UTC by Telsa Gwynne
Modified: 2005-01-16 21:06 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Before I saw Malcom's assignment, I wrote this. (12.94 KB, text/plain)
2002-09-02 17:28 UTC, Peter Williams
Details
GNOME glossary in xml. (24.68 KB, text/plain)
2002-09-18 15:08 UTC, Patrick Costello
Details

Description Telsa Gwynne 2002-08-28 12:46:08 UTC
I am consistently seeing "what's this eel thing?" "why's this scrollkeeper
that this gnome package is asking for in order to compile?" questions on
IRC and mailing lists (particularly IRC).

I started a list of "what on earth is that?" stuff in the gnome 1.2
faq but it obviously doesn't cover gnome 2. Whether or not we have a
faq for gnome 2, we need a list of what all these gnome packages are.

Might help explain the "I have to download _how_ many? why?" question
too :) 

Needs to explain with examples: concepts like embedding are not actually
that well-understood so saying "bonobo lets you embed stuff" doesn't
help.
Comment 1 Malcolm Tredinnick 2002-09-02 01:24:14 UTC
I already have a list like this for my own use. Turning it into a
document is not going to be too hard.
Comment 2 Peter Williams 2002-09-02 17:28:36 UTC
Created attachment 10860 [details]
Before I saw Malcom's assignment, I wrote this.
Comment 3 Malcolm Tredinnick 2002-09-03 00:12:06 UTC
Wow. That is pretty different from what I was going to write, but I
think it fits the bill of what Telsa was after (Telsa: is it?). So in
the interest of saving work and getting more authors' names on things,
let's use it.

If nobody else wants to the markup, I will get to it in a little while
and whack it into CVS.
Comment 4 John Fleck 2002-09-03 04:11:56 UTC
Malcolm -
We've had some offers from people on the docs list/#docs IRC channel
willing to do markup. Perhaps one of them could mark it up and you
could channel your talents elsewhere? I'd be happy to get this
forwarded to the list and underway if you've not already started
marking it up.
- John
Comment 5 Malcolm Tredinnick 2002-09-03 04:24:33 UTC
John: I have not started to do the markup. It would be better for me
if somebody else was to do it, since I have quite a bit to do already.
So I will leave it in your hands. Thanks.
Comment 6 Yanko Kaneti 2002-09-03 14:42:07 UTC
I feel creating yet another description for the modules is somehow
redundant.

After all this info should be in _every_ modules README file. Who is
the maintainer should be in every modules MAINTAINERS file.

How about going a bit further with this and automating the creation.
Lets assume every module has some lines prefixed with "blurb: " in its
readme file.

The only thing needed to get the platform list in shape would be a
list of which modules are in the platform, and I beleve this is
already somehere in the cvs.

Creating such a script and pursuing the modules to update their README
files would create some more consistency between the various modules,
which can only be good, right?
Comment 7 Telsa Gwynne 2002-09-03 15:12:58 UTC
I wholeheartedly agree that the README, MAINTAINERS,
README.cvs-commits and similar files are in deplorable
states in many GNOME CVS modules. And that too should be fixed.

But the people who I am seeing ask these questions are not people
who negotiate CVS with impunity. It's the people who get the package
list, look at the order to compile them, and think "What the hell
are all these? Why so many? What do they all _do_?"

The things they want to know are "why is this scrollkeeper first?
Why isn't it in the same place as all the other gnome packages?"
They want answers like "It indexes the documentation placed on the
system by the other packages, so it has to be there first to see
the rest arrive. It is not on the Gnome site because it is a standard
used by Gnome, KDE and (whoever else). So it is on a 'neutral' site
like sourceforge.". And occasionally things like what the initials
stand for or why that funny name.

The things you want in a README for hackers are not the same. 
I would be most disappointed if I could understand all the README
and READNE.cvs-commits files in all the modules :) You're supposed
to talk about APIs and ABIs and callbacks and regressions and 
relevant specs, not "This is a package that indexes documentation",
surely :) 

Seriously, I agree that the READMEs are lamentably empty, but I
think the information wanted by hackers looking in CVS and by 
people who just want to install GNOME is different.
Comment 8 Yanko Kaneti 2002-09-03 15:33:37 UTC
I didn't make myself clear enough, sorry.

My idea is to generate the friendly list from the contents of the
README , etc. files in cvs. This could easily be automated on
cvs.gnome.org given there is the friendly info in those files. 

Comment 9 Peter Williams 2002-09-03 21:35:09 UTC
Yanko: that sounds like a good idea but it's not going to happen
overnight... whereas if we can get my doc marked up (assuming it's
generally in the right direction; I haven't edited it at all) we'd
have something ready to go.
Comment 10 John Fleck 2002-09-04 00:30:28 UTC
While Yanko's idea seems good in the abstract, I think getting all the
package maintainers to agree on and utilize a standard format to
enable automatic extraction sounds like a bigger headache than just
writing and maintaining a single doc.

And Pat Costello has volunteered to mark this up, so we ought to have
that done by the end of the week (or sooner, if somebody else jumps in
first).
Comment 11 Patrick Costello 2002-09-12 13:00:10 UTC
I have done the markup into xml. If someone wants the xml sources,
then let me know who to send them to. I haven't done any editing or
revising of the list. I'll leave that up to Peter's discretion. 

Pat
Comment 12 Telsa Gwynne 2002-09-12 13:06:13 UTC
I'd dump them into bugzilla as an attachment to this bug.
There's a 'create a new attachment' bit just below keywords
and just above dependencies. 
Comment 13 Peter Williams 2002-09-12 18:44:35 UTC
Feel free to edit as you wish, I haven't done any as of yet. My
personal approach would be to just put the document up somewhere and
address questions as people ask them, although I am not wise in the
ways of documentation so perhaps that's not the best idea.
Comment 14 Patrick Costello 2002-09-18 15:08:01 UTC
Created attachment 11162 [details]
GNOME glossary in xml.
Comment 15 Patrick Costello 2002-09-18 15:11:19 UTC
I've added the file gnome-pkg-glossary.xml to this bug as an
attachment. At some stage in the future, I will probably come back to
this glossary and do some editorial revision. If anyone wants to build
the html file from this xml, they will need the legal.xml file to go
with it. I can let you have a legal.xml if you do not already have
that file. 
Comment 16 Murray Cumming 2003-07-25 09:37:00 UTC
The modules list has cvs http links, so it's easy to read the READMEs.
Isn't this enough?:
http://www.gnome.org/start/2.3/modules/

If modules do not have meaningful READMEs then please do bug them
about it.
Comment 17 Malcolm Tredinnick 2003-07-25 14:17:40 UTC
Reading the README files is definitely not sufficient. Most people
will not have all the source code modules on their system and having
to poke around on a few dozen web pages is very inefficient compared
to reading a single document.

The idea is to eventually put the stuff Peter started into somewhere
like gnome-devel-docs and make a release of that package so that
people have a handy summary available on their system, etc.

This all still needs to be done, but it is lower priority than so many
other things.
Comment 18 Murray Cumming 2003-07-31 12:40:24 UTC
> Reading the README files is definitely not sufficient. Most people
> will not have all the source code modules

It has links to the pages in our cvs web thingy, so I think it's
enough. I guess we could add an extra description column, but I think
it makes sense for module maintainers to maintain their own descriptions.

By all means do something extra if you like, but we should try to make
our definitive modules list as clear as possible.
Comment 19 Telsa Gwynne 2005-01-15 17:36:20 UTC
Elijah's "Developing with Gnome" document has an entire
"What in the world is that?" section now at 
http://www.gnome.org/~newren/tutorials/developing-with-gnome/html/ch05.html
which answers my original bug. 

So I think this bug can be closed, unless we want to pursue the
line of packaging it up into something that gets installed on the
machine as per comment #17 ? 

Comment 20 Malcolm Tredinnick 2005-01-16 21:06:03 UTC
The information already exists online at gnome.org, which was the original goal.
So I agree with Telsa -- this is done.