Re: Patches for Installation Manual, Chapter 1 (welcome.sgml)

["C.M. Connelly" <c@eskimo.com>]

"ADC" == Adam Di Carlo <adam@onshore.com>
"CMC" == C.M. Connelly <c@eskimo.com>

Sorry I haven't gotten back to you sooner; I didn't get your mail
(locally -- I found it in my remote mail spool) and only saw it in
the list archive this morning.

   ADC> Ok -- thanks.  I have some issues with it though.

No problem.

   Me> I also made some fixes and additions in urls.ent, and
   Me> defined two entities that should probably be defined
   Me> elsewhere: emdash and endash. (I don't understand why these
   Me> entities aren't defined at a higher level; please suggest a
   Me> better place for their definitions.)

   ADC> Unnecessary.  We already have &mdash and I think also
   ADC> ndash defined in debiandoc-sgml.  I'm going to deny this
   ADC> patch.

Aha.  I didn't know about those, but that's fine.  (I figured
those entities had to be defined somewhere, but I hadn't realized
their names dropped the initial ``e''.)


   Me> The patches are probably larger than they could be because
   Me> the whitespace has changed.  Sorry about that.  If there's
   Me> some tool that formats SGML in a standard way that other
   Me> folks working on these manuals are using, please let me
   Me> know.  I used Emacs' PSGML mode, and I'm not aware of any
   Me> better tools that don't cost a fortune.

   ADC> That's what I use to.  You can use 'diff -b - u' or,
   ADC> rather, 'cvs diff -b -u'.

Will do.  I was hoping you'd have a pointer to some wundertool,
but I'm not that surprised that you don't.


   welcome> We are delighted that you have decided to try Debian,
   welcome> and sure that you will find that Debian's GNU/Linux
   welcome> distribution is unique.

   ADC> This is awkward language.

Mm.  I'm not sure I completely agree, but what do you suggest?
The original was awkward, too, being broken into two sentences,
with ``We're'' beginning the first and ``We are'' starting the
second.  Combining the two sentences with ``and'' gives the
sentence a bit more flow.  How about something like:

   Thank you for trying Debian!  We are sure that you will find
   Debian's GNU/Linux distribution unique among those available
   today.


   ADC> Please do not indent.  Note how the following PSGML
   ADC> setting is set:

   ADC>   sgml-indent-data:nil

Hmm.  That variable must not have been defined in the file I was
originally working with.  I've tried the current one, and Emacs
won't indent or fill paragraphs even if I tell it to.  Emacs (or
PSGML mode, probably) was responsible for the horrible indentation
in the version of the document that I sent.


   ADC> I've committed your stuff and then modified it.  See
   ADC> welcome.sgml patches I made.  Notably, your comments were
   ADC> a bit excessive and some other stuff.

Great!  I meant the comments more for whoever was reading the
patches than for inclusion in the document itself, so dumping them
is not a problem.


   ADC> Please please please in the future avoid rewrapping
   ADC> paragraphs except when you are really really editing
   ADC> deeply in a file.  Otherwise it's almost impossible for me
   ADC> to pick out what you did.  I don't care if that makes for
   ADC> uneven line breaks.  Saving my time is more important than
   ADC> line breaks being even.

No problem.  It's hard for me to see what changes you made, too,
and I thought the indentation looked terrible, anyway....

More to come....

Thanks,

   CMC

+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
 Behind the counter a boy with a shaven head stared vacantly into space, 
 a dozen spikes of microsoft protruding from the socket behind his ear.
+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
   C.M. Connelly               c@eskimo.com                   SHC, DS
+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+