Re: 2.0 chap-exinst

On Tue, Jul 27, 2004 at 08:41:15PM +0200, Daniel de Kok wrote:
> Good idea, thanks for the hint. I have made a bunch of screenshots, the
> size is right. I'd like to hear whether it is readable (enough) or not.
> 
> ftp://ftp.netbsd.org/pub/NetBSD/misc/daniel/exinst/language.png

I haven't seen any reactions, so I guess the quality is not that awful ;). I
am currently adding the new screenshots, and will update the chapter where
needed.

--

-- 
Daniel de Kok <danieldk <at> pobox.net>

Re: RFC: Chapter 9. Compiling the kernel

On Thu, 29 Jul 2004 18:52:54 +0000, Julio M. Merino Vidal wrote:

>> hmm, well, to build with build.sh we need practicaly to have all /usr/src;
>> many of users fetch only usr/src/sys - without other src for the first time.
> 
> That's true.  So both ways must be explained, suggesting the use of build.sh
> (because you use a sane toolchain, and it allows crosscompilation).

Yes, please see
http://mail-index.netbsd.org/port-macppc/2004/06/29/0002.html and related
discussion for a report from one user who found instructions in the guide
horribly overcomplicated, because the guide instructs to build all tools
(which requires all sources and this is not mentioned in the guide, btw),
which is totally unnecesary.  Don't forget that most of users are running
stable releases and they want to compile the kernel of the same version as
the one which they already have, just to tweak kernel options.

This chapter of the Guide also has at least one error: it mentions the /sys
symlink, which doesn't exist anymore.

A bit offtopic, but why should be all this covered by the Guide, when there
are perfectly fine instructions under www.netbsd.org/Documentation (in this
case, the kernel FAQ)? Those FAQs are very brief, but they give all of the
important informations, which is a great achievement.

They are also much more accurate: the guide tells you to download the
sources with CVS, which is probably the least efficient method, while the
FAQ points you to the syssrc.tgz tarball on the install CD or on FTP.

Of course, all those errors can be corrected. But until this is done, the

Re: RFC: Chapter 9. Compiling the kernel

On Tue, Aug 03, 2004 at 08:39:17AM +0200, Pavel Cahyna wrote:
> On Thu, 29 Jul 2004 18:52:54 +0000, Julio M. Merino Vidal wrote:
> 
> >> hmm, well, to build with build.sh we need practicaly to have all /usr/src;
> >> many of users fetch only usr/src/sys - without other src for the first time.
> > 
> > That's true.  So both ways must be explained, suggesting the use of build.sh
> > (because you use a sane toolchain, and it allows crosscompilation).
> 
> Of course, all those errors can be corrected. But until this is done, the
> guide should not be published IMHO, as it only scares new users. Or it
> should be given as a preview, with big warning that it is under construction
> and possibly inaccurate.

Sending a patch for that particular chapter would be much more useful than
doing that.

--

-- 
Daniel de Kok <danieldk <at> pobox.net>

Content of the Guide (was Re: RFC: Chapter 9. Compiling the kernel)

> > Of course, all those errors can be corrected. But until this is done, the
> > guide should not be published IMHO, as it only scares new users. Or it
> > should be given as a preview, with big warning that it is under construction
> > and possibly inaccurate.
> 
> Sending a patch for that particular chapter would be much more useful than
> doing that.

Well, I am willing to contribute to the NetBSD documentation, and I already
submitted some improvements. But correcting errors in the Guide, when there
already are pages that probably predates it, are more accurate, IMHO better
written and generally less problematic seems to me as a complete waste of time.
By giving examples of errors in this chapter, I wanted to suggest that the
chapters duplicating more accurate information could possibly be abandoned, and
possibly start a discussion about the content of the Guide. For example, why
mention the installation process here? There are installation instructions, no?
The installation instructions in the Guide seems to describe NetBSD 1.5 and only
i386.

Bye	Pavel

Re: Content of the Guide (was Re: RFC: Chapter 9. Compiling the kernel)

On Wed, Aug 04, 2004 at 07:50:57AM +0200, Pavel Cahyna wrote:
> Well, I am willing to contribute to the NetBSD documentation, and I already
> submitted some improvements. But correcting errors in the Guide, when there
> already are pages that probably predates it, are more accurate, IMHO better
> written and generally less problematic seems to me as a complete waste of time.
> By giving examples of errors in this chapter, I wanted to suggest that the
> chapters duplicating more accurate information could possibly be abandoned, and
> possibly start a discussion about the content of the Guide. 

Please, be aware that the guide serves a different purpose. For instance,
there were some plans to print the guide. A printed guide would be useless
for most people if some major topics are only covered on the website. Besides
that I have had many positive comments regarding the guide, and the Dutch
translation. Many people seem to like that they can download one complete
book that introduces them to NetBSD, without having to fill in holes by
searching for other documentation.

> For example, why
> mention the installation process here? There are installation instructions, no?
> The installation instructions in the Guide seems to describe NetBSD 1.5 and only
> i386.

Well, the installation chapter had some debate. In the end it was decided
that it would be good to have an installation chapter, together with a
chapter that shows a sample installation with screenshots. And we are
currently working on a revised chapter, based on NetBSD 2.0. 

--

-- 
Daniel de Kok <danieldk <at> pobox.net>

Re: RFC: Chapter 9. Compiling the kernel

>  Don't forget that most of users are running
> stable releases and they want to compile the kernel of the same version as
> the one which they already have, just to tweak kernel options.

Perhaps someone should look at building semi-custom kernels from
standard object files.

So build (say) (sp,mp)*(normal,diagnostic) objects for everything
and just do the device tree dynamically.

	David

--

-- 
David Laight: david <at> l8s.co.uk

Registration as Documentation Developer

hi,

i'd like to commit work to NetBSDs documentation, especially to the german 
translation. please register me ;)

i'm already listet at

http://netbsd.org/gallery/consultants.html#macfinity

(please take contact data etc. from there except email, this is 
timo.schoeler <at> macfinity.net or the NetBSD one i'd get perhaps? ;)

tia & best regards,

timo

Re: Registration as Documentation Developer

On Fri, Aug 06, 2004 at 03:07:55PM +0200, Timo Schoeler wrote:
> hi,
> 
> i'd like to commit work to NetBSDs documentation, especially to the german 
> translation. 

Great! This page contains instructions how you can help contributing
to the translation of NetBSD-related materials:

http://www.netbsd.org/developers/translate.html

There is a mailinglist for people who'd like to translate NetBSD material
to german:

http://guinness.cs.stevens-tech.edu/mailman/listinfo/netbsd-docs-de

The best way to go from here is probably to choose an untranslated
part of the website or guide, and ask there to check nobody else
is working on that yet.

With kind regards,
Daniel de Kok

--

-- 
Daniel de Kok <danieldk <at> pobox.net>

Re: Content of the Guide (was Re: RFC: Chapter 9. Compiling the kernel)

Sorry for the delay.

> Please, be aware that the guide serves a different purpose. For instance,
> there were some plans to print the guide. A printed guide would be useless
> for most people if some major topics are only covered on the website. Besides

OK, I didn't know that. I did some very quick research and I found that:

- FreeBSD has both a FAQ and a handbook. But FreeBSD probably has much
  more resources to spend on maintaining possibly duplicated information.

- OpenBSD has a FAQ only, whose content seems to be quite similar to the
  various NetBSD FAQs at www.netbsd.org/Documentation, but it is organized
  in chapters and available in the installed system, also in PDF format,
  so it is probably better suited to printing as a book.

Could the goals that you mention be achieved with less duplication of
information and maintenance effort by providing the (possibly
restructured) FAQs instead of the guide, maybe in a manner similar to
OpenBSD?

> that I have had many positive comments regarding the guide, and the Dutch
> translation. Many people seem to like that they can download one complete

See the discussion on port-macppc (cited in one of my previous emails) for
a not-so-positive comment.

Bye	Pavel

chap-kernel fixes

I propose to make the changes in the attached patch to fix chap-kern
a bit. Any comments/objections/...?

-- 
Daniel de Kok <danieldk <at> pobox.com>

Index: chap-kernel.xml
===================================================================
RCS file: /cvsroot/htdocs/guide/en/chap-kernel.xml,v
retrieving revision 1.9
diff -b -u -r1.9 chap-kernel.xml
--- chap-kernel.xml	20 May 2004 03:09:14 -0000	1.9
+++ chap-kernel.xml	13 Aug 2004 12:04:01 -0000
 <at>  <at>  -42,21 +42,29  <at>  <at> 
     <title>Installing the kernel sources</title>

     <sidebar>
-      <para>You can get the kernel sources from AnonCVS, see
-        <xref linkend="chap-cvs" />.</para>
+      <para>
+	You can get the kernel sources from AnonCVS (see
+        <xref linkend="chap-cvs" />), or from the 
+	<filename>syssrc.tgz</filename>
+	tarball that is located in the <filename>source/sets/≤/filename> 
+	directory of the release that you are using. If you use the second
+	method, you can extract the tarball as root: 
+      </para>
     </sidebar>