Process

[Dave Pawson]

On Thu, 2004-08-19 at 19:51, Karsten Wade wrote:

> > 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)
No, its to make it look pretty for humans.
The identity transform I mailed to the list can do the same thing,
quicker and better.

> 
> 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?

Your prior comment indicated you were utilising plain text differences
for a revision changes? Rather than an XML diff. That was my point.
XML has no respect for whitespace in general, hence document layout,
which may be of use in a python or tcl program, has little utility
in XML.



> * Shared authoring in a single XML file.
How does layout impact this Karsten?

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

That's the markup and which tag to use surely? Not pretty printing?

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

Inserts and deletes can be xml markup. plain text diff is far less
useful.

I'd suggest using <ins au="dp">My addition</ins>
and <del auth="kwade"> old content</del>
and then use xml processing to remove deletions, add new material,
but perhaps thats not in line with older processes?



> 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

Fair comment; My objection would be someone else making changes when
an original author hasn't reviewed it for release? Bit of a waste.

> 
> 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. 

Works for me. Whatever.



> 
> 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.

I'd much prefer an xml diff, or semantic markup (ins del). Makes
more sense in an xml process IMHO.


> M-x ispell-buffer

AFAIK that doesn't work in a windows emacs. 'tis all.
I'll try it now I'm on rh! Tks.


> 
> 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?
Isn't there (wasn't there) debate over aspell replacing ispell?

> 
> > 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?
AFAICS there is no reason to use readable id values for other than 
chunked elements, sect1 following current guidelines.
Any more is pure waste of effort.
  Tammy?

> 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.  

Repeating myself; Don't navigate by id values, that's not why they are
there.



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

Find a more reasonable way of navigating. One that's meant for 
people, not machines.


> 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.

If you wish to use last centuries toolchain, there may be a price to
pay.


> 
> > 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. 

Which you state elsewhere?


> 
> 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.

The tool resolving the link should report that as an error. docbook
stylesheets do that, xslt version.

> 
> >   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.

I meant in your document?

-- 
Regards DaveP.
XSLT&Docbook  FAQ
http://www.dpawson.co.uk/xsl