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
