On Tue, 26 Oct 2004 01:12:22 -0400, "Brian A. Seklecki"
<lavalamp@spiritual-machines.org> wrote:
> Yet another draft copy:
> 
> http://digitalfreaks.org/~lavalamp/htdocs/guide/en/chap-misc.html#chap-misc-mkbootable-iso
> 
> ...pending response from some of the more exotic ports on 2.0 updates /
> changes, I'll submit a patch via send-pr(1)

Very nice work.  I hope you don't mind a few random comments on the
overall state of the thing. :-)  

1. Easy ones:

	s/dependant/dependent/g
	s/Ie,/I.e.,/g
	s/ex./e.g./g
	s/not loosing/not losing/
	s/devices wont be made/devices won't be made/
	s/El Torito which are used/El Torito, which is used/
	s/late November, 1999./late November 1999./
	s/ajusts/adjusts/g
	s/relaxedly/calmly/g
	s/we will loose some sectors/we will lose some sectors/
	s/optimize it studying the output/optimize it by studying the output/
	s/ready for usage/ready for use/

(Use "e.g.," or "for example", because "ex." isn't standard English
usage.)

2. Intead of:

	(substitute the names ot the servers in the example 
	with the ones that you are actually using. Option 	

   this:
	(Substitute the names ot the servers in the example
	 ^ 
	with the ones that you are actually using.) Option 	
	                                          ^

  Similarly, instead of:

	(in the following paragraphs it will be explained how to create a CD
compatible with both Joliet and Rock Ridge. 

  this:
	(In the following paragraphs it will be explained
	 ^
	how to create a CD compatible with both 
	Joliet and Rock Ridge.)
	                      ^ 

3. As a general comment, I wish the commands, filenames, and environment
variables were consistently tagged such that they were typographically
distinct in a typical HTML browser.  For example, "ntpdate" and
"mksunbootcd" sometimes appear as ordinary text, and other times as
filenames ("<tt class="filename">mksunbootcd</tt>").  Similarly, in this
bit:

	${TOOLDIR} should be evaluated to the value of the "-T" flag to build.sh,
and ${ARCH} should be evaluated to the output of when passed the "-m"
flag.

The options "-T" and  "-m" shouldn't appear in quotes, but rather should
be visually distinct by virtue of being tagged as command line options. 
(And they should be called "options", not "flags", no?  After all, it's
getopt(1), not getflg(1).)  ;-)

4. Take care with "only":

	this only changes the partition numbers

  should be:
	this changes only the partition numbers

5. Instead of:

	 Thanks to the NTP protocol it is possible to adjust the clock of a
single workstation but also to synchronize an entire network.

  this:
	 Thanks to the NTP protocol, it is possible to adjust the clock of a
single workstation or synchronize an entire network.

6. There are many places where ".)" is used when ")." should be. 
According to Follett's "Modern English Usage", the period goes inside the
closing parenthesis when it belongs to what's enclosed, else after.  By
that rule, 

	 it is better to check that there is sufficient space on the hard disk
for the data that you are writing (up to 700MB.) 

   should be:
	 it is better to check that there is sufficient space on the hard disk
for the data that you are writing (up to 700MB). 

There are several such.  

The document frequently uses a casual form, parenthesizing an independent
clause at the end of a sentence.  I'm not sure how that should be
punctuated.  For instance:

	 This format is usually not readable by Unix systems (it is supported by
NetBSD-current.) 

I suppose that's fine.  I would render it as two sentences:

	This format is usually not readable by Unix systems. (It is supported by
NetBSD-current.) 

because then it's clear where the periods belong. 

7. In section 25.2.1. (Creating the ISO image), I suggest that ISO9660,
Joliet, and Rock Ridge be made subordinate titles.  

8. Who is "me" and "I" in this document?  Do we want it in first person?  

+++

I hope these points are useful.  

If you like my ideas, I'd be willing to participate in the effort more
directly and review the whole thing.  I'm not set up atm to build the
guide (at least, I don't think so), but that's fairly easily remedied.  

Regards, 

--jkl