headers
Julio M. Merino Vidal | 1 Jun 2005 17:11
Picon

Reformatting faq.xml

Hi!

I'd like to do some changes in the FAQ section in the guide.  Basically,
group all existing questions in a "General questions" section and then
add another block with GNOME-related questions of interest (more
sections could follow).

But when going to do so, I found the xml file very hard to read,
specially due to the inconsistent indentation.  So I removed it from the
main tags (chapter and sections) and only left it for structures that
are worth noticing (lists).  (Indentation in Docbook files gets in the
way as a little change in the structure will require you to reindent the
whole document...)

Furthermore, it was incorrectly formatted in some cases.  For example,
there must be no space between an element and CDATA, as in '<para>some
text</para>', not '<para> some text </para>'.  Check this out:

http://mail-index.netbsd.org/www-changes/2005/05/06/0000.html

So before doing big changes to the content, I've reformatted the file.
There is a copy here (there is no sense in making a diff because almost
all lines change):

ftp://ftp.NetBSD.org/pub/NetBSD/misc/jmmv/faq.xml

Any objections in doing this?

Thanks,
(Continue reading)

Permalink | Reply |
headers
Hubert Feyrer | 1 Jun 2005 15:44
Picon
Favicon

Re: Reformatting faq.xml

On Wed, 1 Jun 2005, Julio M. Merino Vidal wrote:
> I'd like to do some changes in the FAQ section in the guide.  Basically,
> group all existing questions in a "General questions" section and then
> add another block with GNOME-related questions of interest (more
> sections could follow).

Er, what kind of GNOME related information do you intend to put in a 
seperate FAQ section?

When I last re-organized the Pkgsrc Guide, (which I assume you're talking 
about here, in contrast to the NetBSD Guide?), I found that the FAQ 
section became the dumping place for all questions that people didn't want 
to find a better place (probably because they didn't read it entirely).
And your plan of moving all existing FAQs into a seperate sections sounds 
like that again.

> So before doing big changes to the content, I've reformatted the file.
> There is a copy here (there is no sense in making a diff because almost
> all lines change):
>
> ftp://ftp.NetBSD.org/pub/NetBSD/misc/jmmv/faq.xml
>
> Any objections in doing this?

Assuming there's no content change, only whitespace, that's fine with me.

  - Hubert

--

-- 
Genervt von Viren und von Viren versandten Spam-Mails?  -> www.NetBSD.de
(Continue reading)

Permalink | Reply |
headers
Julio M. Merino Vidal | 1 Jun 2005 18:52
Picon

Re: Reformatting faq.xml

On Wed, 2005-06-01 at 15:44 +0200, Hubert Feyrer wrote:
> On Wed, 1 Jun 2005, Julio M. Merino Vidal wrote:
> > I'd like to do some changes in the FAQ section in the guide.  Basically,
> > group all existing questions in a "General questions" section and then
> > add another block with GNOME-related questions of interest (more
> > sections could follow).
> 
> Er, what kind of GNOME related information do you intend to put in a 
> seperate FAQ section?

Well, I was thinking of user questions, not how to do specific stuff in
pkgsrc (which is what was in the FAQ before).  For example:

1) How do I install GNOME?  (explain the difference between gnome-base
   and gnome)
2) Why does the gnome meta package depend on <foo>?  (explain the
   rationale rationale behind the dependency tree)
3) Why does the help|contents menu item do not work?  (missing yelp)
4) I installed gstreamer and gst-plugins, but I can't play any media
   files.  Why?
5) Why does the trash show no files?  (see PR number ...)

I think I had some more ideas in my mind... but can't remember them now.
Do you feel this is OK?

> When I last re-organized the Pkgsrc Guide, (which I assume you're talking 
> about here, in contrast to the NetBSD Guide?), I found that the FAQ 
> section became the dumping place for all questions that people didn't want 
> to find a better place (probably because they didn't read it entirely).
> And your plan of moving all existing FAQs into a seperate sections sounds
(Continue reading)

Permalink | Reply |
headers
Hubert Feyrer | 1 Jun 2005 17:39
Picon
Favicon

Re: Reformatting faq.xml

On Wed, 1 Jun 2005, Julio M. Merino Vidal wrote:
> Well, I was thinking of user questions, not how to do specific stuff in
> pkgsrc (which is what was in the FAQ before).  For example:
>
> 1) How do I install GNOME?  (explain the difference between gnome-base
>   and gnome)
> 2) Why does the gnome meta package depend on <foo>?  (explain the
>   rationale rationale behind the dependency tree)
> 3) Why does the help|contents menu item do not work?  (missing yelp)
> 4) I installed gstreamer and gst-plugins, but I can't play any media
>   files.  Why?
> 5) Why does the trash show no files?  (see PR number ...)
>
> I think I had some more ideas in my mind... but can't remember them now.
> Do you feel this is OK?

Hmmm, not sure. This is about documentation about running some 3rd party 
application on NetBSD. I don't think we have a place for such 
documentation right now. Places that come to mind are the pkgsrc guide (as 
you suggested), the NetBSD guide, or somewhere in htdocs. I recommend 
asking for advice on netbsd-docs <at> .

If the pkgsrc guide is it, I'd say add "Package specific directions" 
similar to #13.5, and add it as seperate section between "5. Creating 
binary packages" and "6. Frequently Asked Questions".

> I'm also thinking about rewriting some of the section headers to be
> questions (which the attached patch does not do), and maybe rewrite the
> sysconf stuff I wrote a while ago (because part of it does belong to the
> developers section, not the FAQ).  Anyway, all of these will be separate
(Continue reading)

Permalink | Reply |
headers
Julio M. Merino Vidal | 2 Jun 2005 01:05
Picon

Re: Reformatting faq.xml

On Wed, 2005-06-01 at 17:39 +0200, Hubert Feyrer wrote:
> On Wed, 1 Jun 2005, Julio M. Merino Vidal wrote:
> > Well, I was thinking of user questions, not how to do specific stuff in
> > pkgsrc (which is what was in the FAQ before).  For example:
> >
> > 1) How do I install GNOME?  (explain the difference between gnome-base
> >   and gnome)
> > 2) Why does the gnome meta package depend on <foo>?  (explain the
> >   rationale rationale behind the dependency tree)
> > 3) Why does the help|contents menu item do not work?  (missing yelp)
> > 4) I installed gstreamer and gst-plugins, but I can't play any media
> >   files.  Why?
> > 5) Why does the trash show no files?  (see PR number ...)
> >
> > I think I had some more ideas in my mind... but can't remember them now.
> > Do you feel this is OK?
> 
> Hmmm, not sure. This is about documentation about running some 3rd party 
> application on NetBSD. I don't think we have a place for such 
> documentation right now. Places that come to mind are the pkgsrc guide (as 
> you suggested), the NetBSD guide, or somewhere in htdocs. I recommend 
> asking for advice on netbsd-docs <at> .

I think the pkgsrc guide is the right place because several questions
are related to how we handle the specific packages in pkgsrc.  Will ask
in netbsd-docs, though, when I "finish" something else... (see below).

> If the pkgsrc guide is it, I'd say add "Package specific directions" 
> similar to #13.5, and add it as seperate section between "5. Creating 
> binary packages" and "6. Frequently Asked Questions".
(Continue reading)

Permalink | Reply |
headers
Hubert Feyrer | 1 Jun 2005 23:38
Picon
Favicon

Re: Reformatting faq.xml

On Wed, 1 Jun 2005, Julio M. Merino Vidal wrote:
> Hmm yes, a new chapter may be good if we want to keep the FAQ one at a
> minimum.

Yes, please! A seperate section with a more appropriate heading than "FAQ" 
is welcome in most cases, FAQ will become a "wastedump" over time (again) 
anyways (generally speaking ;-).

> I think I've opened a can of worms touching this... you know ;)

No, really? ;-) ;-) ;-)
(All of our documentation is a can of worms! :/)

> Started resorting that question and ended up creating a new chapter
> about the pkginstall framework.  It's still incomplete, but you can see
> the outline and the "configuration files" section already written in:
>
> ftp://ftp.NetBSD.org/pub/NetBSD/misc/jmmv/pkginstall.diff
>
> Comments about the structure/ideas?

Looks very good!

> If it's OK, should I first commit it as is (incomplete), saying that
> it's a rewrite of we have now (no more "unrelated" things), or should
> everything be added at once?

Hm... if you think the new (incomplete) version's better than what we have 
now, commit it, and update the PDF/HTML/etc. files. I guess you can always 
commit the XML files, I'm not doing any work on the pkgsrc guide, and I
(Continue reading)

Permalink | Reply |

Gmane