Test email. Too quiet?

[Karsten Wade]

On Thu, 2004-08-19 at 10:27, Dave Pawson wrote:
> On Thu, 2004-08-19 at 10:04, Karsten Wade wrote:
> 

Thanks for the fast reply; glad you like it overall.  I wanted to
address a few of your points ...

> One of the reasons for using Emacs is that it is capable of indenting
> the code according to the DTD.
>    DTD's aren't fashion or style statements. No such thing as indenting
> in a DTD.
> If this project is going to use non-xml tools for diff generation,
> admit it as a shortcoming and apologise :-)

I think we are talking about different things here.  Clearly, I'm not
the expert, so perhaps you can clue me in as to what I _am_ talking
about. :)

a) Emacs can auto-indent according to PSGML(X)'s understanding of
___________ 

(I thought it indented according to nesting defined in the DTD)

b) The indenting I am interested in has to do with code readability, not
directly about making sane diffs.  Was your clever XSLT trick for
standardizing indenting prior to diff'ing, to make for a sane diff?  I
can see where it would resolve that area, but we have to consider other
areas:

* Shared authoring in a single XML file.

* The need for code standardization across the project, as is common in
other open source projects.

* An editor's ability to quickly supply useful patches instead of
hunt-and-paste comments.

> If you do not have usable Web space, look for willing hosting partners
> in the project, who can build and host your beta documents.
> controversial recommendation? open
>    +1. I'll host it. Maybe also Brad?
>    Less sure about the XML. My principle has always been keep the source
> to yourself until you're ready? Issue of two people concurrently making
> mods? XML patches are (IMHO) better against a finished document?
> Comments yes, but that can be against html.

I think we need to release the source code with the beta documentation.

* It's a good learning experience for other writers.

* It helps editors/other contributors catch XML coding, syntax, etc.
mistakes early before they are used throughout a document

Not to be harsh, but if you mean "comments ... against html" in the
style of what you did in this email, that is *very* hard to work with. 

I have to open my source file separately and guess where you are talking
about.  Context is lost entirely, and there are no semantic marks (+,-,
>, # etc.) to differentiate between what I wrote and what you wrote. I'd
much prefer a diff, even if I can't patch it but have to manually paste
it into the XML.

> Spell check all files.
>    How, if emacs is used? spellcheck in xml I haven't done. (Or is that
> obvious?)

M-x ispell-buffer

If you don't have ispell installed, you can do 'M-x spell-buffer'.  Not
sure off-hand why ispell is better, shared system dictionary perhaps?

> Verify that all sections have an id so all HTML files generated have
> static filenames.
>   Disagree. Overboard | unnecessary IMHO. Chunking is currently at sect1
> level.

YHO is very strong in this area, but you haven't answered the issues
raised so far.  Until you do, how can we reach consensus?

* No DocBook automatic filenames are useful, that I have seen so far.  
The best so far, ch06s02.html, does not help find where in the XML that
page came from.  

The meaning in a name like ch06s02 relates to the Table of Contents
only, which only shows what order the XML files are called in by the
parent file, not which file something is in.  

My only choice is to open up the document, go to the ToC, and start
counting down for Chapter 6, Section 2, and hope that it's not in fact a
third or fourth level of nesting, because the ToC doesn't display those,
and then I'm entirely lost.

* Filenames that correspond to ID tags that are searchable are useful
for editors, collaborators, and inheritors of a document.  It makes it
easier to learn the document, and faster to fix bugs and author new
content.

* All of this is magnified when you are dealing with a book that is
hundreds of printed pages and dozens of lengthy XML files.

The last point is really important ... I have saved myself _hours_ of
hunting for file locations because of HTML filenames based on ID tags. 
I can't see dropping that contextually valuable information for any
reason.

BTW, the usage of the word 'static' in this directive means, predictable
HTML filenames based on the ID tag.  For example, without ID tags, HTML
filenames in some toolchains will be changed if you didn't clean out the
target directory.

> Verify the HTML Output:
>   Redundant, since its not the authors html that will be used.
> If we can't trust the toolchain to generate good links ....

This is mainly for external URLs, rather than internal linking. 

I agree, I've never seen the toolchain build a link that was broken,
although it sometimes goes to the incorrect location (i.e., writer
target error.)  That is usually visually understood -- as you read
through the document, the <xref> is not where you expect it to be; no
need to click, just fix in XML.

>   How about a list of links (appendix)?

A "References" section should be mentioned; that's pretty common. I will
include that if it's not in e.g. the example-tutorial.

>   Not mentioned: Managing revisionss (fc2 vs fc3 etc) Should be in
> author section?

Good point.  We haven't discussed this.  Areas I see are:

* CVS branching process (file a bug, basically)
* How to handle this at f.r.c/docs
* ???

Thanks - Karsten
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41