[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

"C.M. Connelly" <c@eskimo.com> writes:

> Enclosed please find a set of patches for the first chapter of the
> Installation manual (boot-floppies/documentation/en/welcome.sgml)
> and boot-floppies/documentation/urls.ent.

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

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

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

> Also note that the documentation build currently breaks while
> trying to build the Finnish docs.  It looks like a whole slew of
> identifiers aren't defined in the SGML files.

All this has been fixed by me recently.  Nice to see you found that
problem though -- that shows you have a clue how to build the stuff.

> My plan is to work my way through the entire manual, but I thought
> it would be a good idea to get some feedback before I get too
> involved.  I'm especially interested in filling in some of the
> holes in the PowerPC documentation.


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

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

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

This is awkward language.

> +&debian; brings together high-quality free software from around the
> +world, integrating it into a coherent whole.  We believe that you will
> +find that the result is truly more than the sum of the parts.
> +<p>
> +This chapter provides an overview of the Debian Project and &debian;.
> +  If you already know about the Debian Project's history and the
> +  &debian; distribution, feel free to skip to the next chapter.

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


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

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

.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>

Reply to: