Re: Patches for Installation Manual, Chapter 1 (welcome.sgml)
"ADC" == Adam Di Carlo <email@example.com>
"CMC" == C.M. Connelly <firstname.lastname@example.org>
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.
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
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
ADC> Please do not indent. Note how the following PSGML
ADC> setting is set:
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....
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 email@example.com SHC, DS