Re: DOCBOOK: docbook vs latex
From: Doug du Boulay [EMAIL PROTECTED] To: [EMAIL PROTECTED] Subject: Re: DOCBOOK: docbook vs latex Date: Thu, 05 Sep 2002 19:03:22 +0900 the mml:math tag cleanly separates the actual mathematics from the surrounding paragraph information. Contrast that with the relegation of maththeorem to a perverted mml: module like this mml:math mml:maththeorem mml:title mml:para mml:inlineequation mml:applymml:divide//mml:apply /mml:inlineequation /mml:para /mml:title /mml:maththeorem /mml:math Well, I honestly don't know if MathML provides the document-level blocks that would be needed (you might need a separate module, for that). However it certainly shouldn't be polluted with things like title, para, inlineequation, etc. The standard DocBook versions of those elements should be used. Furthermore, what's needed is a schema language (sorry, I don't know anything about the W3C XML Schema Language) in which a module can allow specific *classes* of the standard DocBook elements within the content models of the elements it provides. While cases like 'title' and 'para' would best be addressed explicitly, a module should be able to implicitly add its own elements to the content models of elements provided by other modules (by appending them to some sort of class). Similarly, it should be able to selectively contribute its elements for use in both specific docbook elements and classes of elements, but also in unknown elements provided by other modules. (from a subsequent message): I guess Matt's last email and this message from the archives pretty well hits the nail on the head: http://lists.oasis-open.org/archives/docbook/200202/msg00087.html Sugoi desu - thanks for digging that up! Domo arigatou gozaimasu. Matt Gruenke _ Chat with friends online, try MSN Messenger: http://messenger.msn.com
Re: DOCBOOK: On the size of DocBook...
[this is a long posting -- I didn't have time to make it more concise] Norman Walsh [EMAIL PROTECTED] writes: The recent thread about DocBook and LaTeX raised the issue of the size of DocBook (measured as the number of elements). (It's not the first thread to raise the issue, just the most recent.) [...] Whenever I think of adding new elements to DocBook, I think about these content models and wonder if it's really worth it. Now, in a sense, this is completely unfair. It's quite possible that the proposed element is just as valuable, to someone certainly and to everyone maybe, as, say errorcode. The fact that errorcode got there first doesn't seem like a very satisfying criteria on which to choose between them. I absolutely agree with this. I don't think the there are already too many elements argument should prevent the TC from giving very careful and objective consideration to adding elements that really should be in there. Take the proposed url element for example. I'm sure not everybody would agree that should be added, but I think Elliotte Rusty Harold has stated some good reasons for adding it -- and adding it as a new element, not as a new class value on another element. aside [I know I've already said this, but I'll take the opportunity to trot the hobbyhouse back out...] I think we also need to be careful about trying to solve the there are already too many elements issue just by adding new class values on existing elements -- systemitem or whatever -- rather than adding them as new elements. It seems like adding new class values increases the complexity of the DTD just as much, but does it in a way that obscures the complexity more. What I mean is, when that's done, it's still adding to the overall number of logical units or semantic components in the DTD. But it's just adding them in a way that makes those logical units: * less intuitive to users * less versatile (you can't sub-class attributes) /aside [...] A few things occur to me. 1. The difference between 400 elements and 800 elements isn't significant, just add 'em all. Sort of a straw man, I think :-) 2. 400 is just too many, we need to make DocBook smaller. A straw man with a little less straw? Given the backward compatibility issues and user-community needs, this seems like the least-likely-to-happen solution -- and maybe the least desirable. 3. Some sort of pizza cutter a la TEI could be invented to allow selection of just the right elements. (But what will that do to interchange?!) 4. Refactoring the parameter entity structure in a more satisfying way might make it easier to customize which would offer some sort of a compromise between 1 and 3. Definitely not straw men. I think we ought to consider these carefully. (For anybody who doesn't know what the TEI pizza cutter is: basically, it's a sort of configurator that lets you choose sets of elements that you want to include or not include in the DTD you use for authoring your documents, and then generates a custom DTD that includes just the element sets you want and excludes the rest.) First, I think implementing 3 might actually require that we do 4. I'm not sure a really useful pizza cutter would even be practical with the current parameter entity organization, at least not the parameter entity organization at the information-pool level. I think TEI was actually designed around the specific requirement to include/exclude element-sets at the information-pool level, and DocBook wasn't nearly as much. But all that said, I wonder whether that kind of parameter-entity reorg is possible and/or prudent. There's a paragraph in Eve Maler and Jeanne El Andaloussi's Developing SGML DTDs that reads: Some DTD implementors choose to store declarations for individual element types (particularly those in the information pool) in separate modules, building up a so-called element library that can be recombined in different ways for different DTDs. However, in our experience the complex interdependencies between information pool elements are easier to understand and maintain if the entire information pool is stored in a single module, with marked sections used to modularize individual element types. Anyway, about the question at the end of number 3 above -- But what will that do to interchange? -- It seems like interchange isn't an issue if * the customized DTDs are strict subsets of the complete DTD * and users/user communities treat their customized DTDs as authoring DTDs and continue to use the full DTD for validation (that is, don't expect that DTDs that others interchange with their community will validate against their custom authoring-DTD subset) Which makes me think of another possibility to add -- something that's sort of already been discussed on this list: 5. The DocBook TC, with suggestions/feedback from the various DocBook users communities, produces a set of standard off-the-shelf strict-subset
Re: DOCBOOK: On the size of DocBook...
On Thu, Sep 05, 2002 at 09:39:25AM -0400, Norman Walsh wrote: 3. Some sort of pizza cutter a la TEI could be invented to allow selection of just the right elements. (But what will that do to interchange?!) People tempted by this approach may want to get a look on the dtd-customizer specs at http://savannah.gnu.org/projects/dtd-cust/. Note there are newer ideas in the July slides than in the specs, which I still have to update. The idea is to allow people to define DTD subsets (or any variant for those wanting that) in a simple and intuitive way. That should allow current dtd-aware authoring tools to provide a more accurate environement, while still allowing to use standard stylesheets. -- Yann Dirson [EMAIL PROTECTED] http://www.alcove.com/ Technical support managerResponsable de l'assistance technique Senior Free-Software Consultant Consultant senior en Logiciels Libres Debian developer ([EMAIL PROTECTED])Développeur Debian
DOCBOOK: manual chunking with my chunk-manual.xsl
Hi,
thanks to norm who wrote this beatiful chunkfast.xsl just in time.
I am writing a customization which can give docbook authors the
possibility to chunk section manual by including a ?dbhtml
Procession instructions and i was just thinking about these really
hairy XPath expression in chunk.xsl about finding next and prev...
i was wondering how easy it was to write this customization after
understanding how things work together. This code is poorly tested
because i just want to ask if i am moving in the right direction. So
heres my module, but it only works with norms
http://nwalsh.com/chunk.xsl and http://nwalsh.com/chunkfast.xsl
posted earlier today and is only tested with 1.53.0 and libxslt 1.20
What it does is just modifying the template named chunk which
determines if a node is a chunk or not. To check it out it looks for
PIs and combines the result of examaning the PIs with the parameters
$chunk.section.depth and $chunk.first.sections
Any comments are very appreciated.
so heres my code. (i don't know if it is allowed to include
attachments).
kind regards,
janning
-- chunk-manual.xsl --
?xml version=1.0?
xsl:stylesheet xmlns:xsl=http://www.w3.org/1999/XSL/Transform;
version=1.0
!--
2002, written by [EMAIL PROTECTED],
1) you can decide via Processing Instruction
if you want to chunk the childs of the parent node of the PI
2) you can override the value of chunk.first.sections via PI
Put PIs like this into your chapter, section, sect1, sect2 ...
?dbhtml chunk-childs=1 chunk-first-sections=0?
chunk-first-sections is inherited by all subsequent childs if not
changed again by another PI
chunk-childs affects only the childs of the parent node of the PI
(put your PI _into_ a chapter to chunk the sections inside this
chapter
you can only decide to
- chunk all childs but not the first
- chunk all child including the first
- chunk no childs
NO WARRENTY, most of the code is copyright by norm walsh, i guess
the few other characters can be used as you'd like :-)
--
xsl:import href=chunkfast.xsl/
xsl:template name=dbhtml-chunk-childs
xsl:param name=pis select=./processing-instruction('dbhtml')/
xsl:call-template name=dbhtml-attribute
xsl:with-param name=pis select=$pis/
xsl:with-param name=attributechunk-childs/xsl:with-param
/xsl:call-template
/xsl:template
xsl:template name=dbhtml-chunk-first-sections
xsl:param name=pis select=./processing-instruction('dbhtml')/
xsl:call-template name=dbhtml-attribute
xsl:with-param name=pis select=$pis/
xsl:with-param
name=attributechunk-first-sections/xsl:with-param
/xsl:call-template
/xsl:template
xsl:template name=chunk
xsl:param name=node select=./
!-- returns 1 if $node is a chunk --
xsl:variable name=dbhtml-chunk-childs
xsl:call-template name=dbhtml-chunk-childs
xsl:with-param name=pis
select=$node/parent::*/processing-instruction('dbhtml')/
/xsl:call-template
/xsl:variable
xsl:variable name=dbhtml-chunk-first-sections
xsl:call-template name=dbhtml-chunk-first-sections
xsl:with-param name=pis
select=$node/ancestor::*[contains(./processing-instruction('dbhtml'),'chunk-first-sections=')][1]/processing-instruction('dbhtml')/
/xsl:call-template
/xsl:variable
xsl:if test=$node/@id = 'a1s1'
xsl:message
xsl:value-of select=$node/@id/: xsl:value-of
select=$dbhtml-chunk-first-sections/
/xsl:message
/xsl:if
xsl:choose
xsl:when test=not($node/parent::*)1/xsl:when
xsl:when test=local-name($node) = 'sect1'
and ( $dbhtml-chunk-childs = 1 or
($chunk.section.depth gt;= 1 and $dbhtml-chunk-childs = '') )
and ( ($dbhtml-chunk-first-sections = 1 or
($chunk.first.sections != 0 and $dbhtml-chunk-first-sections = '') )
or count($node/preceding-sibling::sect1)
gt; 0)
xsl:text1/xsl:text
/xsl:when
xsl:when test=local-name($node) = 'sect2'
and ( $dbhtml-chunk-childs = 1 or
($chunk.section.depth gt;= 2 and $dbhtml-chunk-childs = '') )
and ( ($dbhtml-chunk-first-sections = 1 or
($chunk.first.sections != 0 and $dbhtml-chunk-first-sections = '') )
or count($node/preceding-sibling::sect2)
gt; 0)
xsl:call-template name=chunk
xsl:with-param name=node select=$node/parent::*/
/xsl:call-template
/xsl:when
xsl:when test=local-name($node) = 'sect3'
and ( $dbhtml-chunk-childs = 1 or
($chunk.section.depth gt;= 3 and $dbhtml-chunk-childs = '') )
and ( ($dbhtml-chunk-first-sections = 1 or
($chunk.first.sections != 0 and $dbhtml-chunk-first-sections = '') )
or count($node/preceding-sibling::sect3)
gt; 0)
xsl:call-template name=chunk
xsl:with-param name=node select=$node/parent::*/
AW: DOCBOOK: Re: AW: [QUESTION] page numbers in sets/books
hello, i finally managed to get a footer the way i wanted it to be. allthough it wasn't that easy :( now i am still struggling with two other issues. 1) i don't like the set's titlepage layout 2) footer/header are not justified in the same way as text paragraphs. maybe you are able to help me with the last one. example page: my header - 1.1 chapter foobar some text some text some text some text some text some text some text some text some text some text some text some text some text some text some text some text some text some text some text some text - my footer page x of y as you can see there is a gap between the rules and the actuall text. but i want the rules to be as wide as the paragraph text. i did not change any margine parameters. so i do not have an idea what could be the problem. regards daniel s. haischt -- -Ursprungliche Nachricht- Von: Norman Walsh [mailto:[EMAIL PROTECTED]] Gesendet: Donnerstag, 5. September 2002 20:19 An: Daniel S. Haischt Cc: [EMAIL PROTECTED] Betreff: DOCBOOK: Re: AW: [QUESTION] page numbers in sets/books / Daniel S. Haischt [EMAIL PROTECTED] was heard to say: | to diplay page / pages, i used the following lines in | my custom stylesheet. | | [fo:page-number/ / fo:page-number-citation ref-id=number-panel/] | | to make it clear, now every book will be numbered | beginning with one as i wanted it to be. but now | the counting of pages does not work any longer. | | any ideas? My guess is the element with id 'number-panel' appears on page 4 of some book. You'll need to make sure that's some content on the last page, and you'll have to make sure that you vary it on a per-book basis. Be seeing you, norm -- Norman Walsh [EMAIL PROTECTED] | To create a little flower is the http://www.oasis-open.org/docbook/ | labour of ages.--Blake Chair, DocBook Technical Committee |
Re: DOCBOOK: On the size of DocBook...
At 12:42 06/09/2002, Michael Smith wrote: Anyway, about the question at the end of number 3 above -- But what will that do to interchange? -- It seems like interchange isn't an issue if * the customized DTDs are strict subsets of the complete DTD * and users/user communities treat their customized DTDs as authoring DTDs and continue to use the full DTD for validation (that is, don't expect that DTDs that others interchange with their community will validate against their custom authoring-DTD subset) I had an 'ah ha' moment at xml-extreme this year. People don't give a ... about markup validity. Its our XML tools that do. The 'authoring' environment vs the 'interchange' environment? Hence Michaels point is quite valid. If they are all good subsets then we shouldn't see that problem. One of the values of having a set of standard strict-subset authoring DTDs is that would be carefully considered by the TC, potentially a lot more carefully than possibly-not-compatible-with-one-antoher ad-hoc custom authoring DTDs that users from the same community might end up creating and propagating and using. What impact might that have on the stylesheets Norm? Divergent sets of stylesheets for pizza slices? What I mean is, I think maybe there are some identifiable DocBook user sub-communities within which users have the same basic markup needs -- their needs within their community are not that radically different from one another. If the TC doesn't produce a subset that meets their needs, and that community is not well-organized enough to produce a suitable custom authoring DTD on its own, we risk having individual users within those communities producing conflicting, sub-optimal customizations. IMO it's the combination of dtd and stylesheets that make it what it is. One without the other would be a minor nicety. My experience is that users and user communities -- especially those that might be considered casual document authors (for example, individual open-source developers who write docs for their own applications) really, really, don't like to be told, DocBook is highly customizable -- go ahead and customize it to meet your needs. It seems like what they want typically want instead is something that just works right off the shelf. Bottom line its just too hard unless you've been there before? Time could be better spent elsewhere. That's it for now. But I really hope we can continue the discussion about this and maybe arrive at some resolutions. Picking up Pauls point, user demand is for 'less necessity' for customisation, i.e. easier out of the box usage. Less tags in a vertical slice of pizza, i.e. still valid to BBdocbook (big brother), but 'appropriate' to my niche? The stylesheets? I'd leave that to Norm. I have a nasty feeling they *could* ride such a divide? regards DaveP
Re: DOCBOOK: On the size of DocBook...
At 21:32 2002 09 05 -0400, ed nixon wrote: Paul Grosso wrote: At 15:36 2002 09 05 -0400, ed nixon wrote: Paul Grosso wrote: snip/ A big problem for me is that I still have not seen a satisfactory explanation of the user requirement(s) that is(are) driving this discussion. You are right, of course. I think the people who read this list regularly become aculturated to the atmosphere of an exchange. For example, the implicit, assumed goal that I saw immerging is two-fold: 1. significantly accelerate the learning curve of new and inexperienced users of the DocBook schema I understand the desire to reduce the learning curve, but I'm not convinced reducing the size of the DTD does that. Reducing the number of tags in the DTD to N doesn't make it any easier for a user to learn the M N tags s/he wants to use. You can make it easier to learn by just learning the ones you need, you don't have to reduce the number in the DTD. 2. further reduce the support overhead of this and the APPS list significantly for a certain class of question by simplifying and/or compartmentalizing. I detected that in the wind over the past months; I assume there are others who have developed the same impression. Perhaps not. Most people ask what tag do I use to do X? I don't see how removing tags so that X can no longer be done reduces the overhead. snip/ What user requirements do bolting or unbolting components of a per application basis address? Are there significant and identifiable genres of DocBook application? For example, is there a significant delimitable difference between the markup required for software versus hardware documentation? Are there other types of publication that lend themselves to a segmentation exercise of some sort? I believe splitting up the DocBook app into genres just adds yet another complication to learning it. (Which genre do I learn, and what if it turns out the way the DocBook committee split things into genres doesn't work for my app?) Personally, I see three disadvantages of that: 1. someone has to do the bolting for a given application; 2. the tools have to support bolting/unbolting; 3. as soon as you bolt together one setup, someone is going to want/use/expect a tag you didn't bolt in. Yes. And that's what I meant by the difficult challenge of what to do, how and when. But the DocBook direction has always been toward customization. Is there an easier way, or a more generic way of doing it? Or, put in terms of user requirements, I see your suggestion accrues negative rather than positive points in the corresponding three (plus) user requirement areas: 1. I can use the off-the-shelf DocBook application with no extra work. Could you please list them for me? I gather Epic makes the claim and there are one, perhaps two of the under $100 editors. Are there a significant number of others? Using current, XML versions of DocBook? I use XMetaL and it is, unfortunately, a fair amount of work just getting something into the editing area that looks half-decent. Getting to a really smooth and robust editing environment for a MSWord convert is a tremendous amount of work. I'm saying the statement #1 above is a user requirement (or perhaps user goal would be more accurate). I'm not saying it is necessarily currently a true statement. I have to admit I haven't done a survey lately, but I do believe there are tools out there. Even if you're just talking about using XSLT, you can point your XSLT processor to the DTD and stylesheets on the web right now without touching them. If you require bolting, you can no longer do that. 2. I can find lots of tools that handle my application with little or no configuration. Lots? Same as above? Same as above. 3. I can expect all of DocBook to be available; I can use TDG as a reference with no surprises; All of DocBook and the general, newbee, somewhat doubtful about this new markup and controlled editing thing freezes in his tracks, confounded by a wealth of (to him) meaningless choice. No surprises? This is clearly not the case, Paul, otherwise there would be significantly less traffic on this list. Every day there are surprises and inconsistencies because it is all a living, breathing, evolving system. There would be more surprises if someone found a tag in TDG that they thought did what they want and they tried to use it but are told that tag doesn't exist. Right now, the list never hears about those that used TDG, found a tag, tried it and liked it. Once you have different DTDs, people are going to find that DocBook isn't just DocBook, TDG doesn't really document their application, and someone on the list will say you should use to FOO tag but the user will then find their genre doesn't include the FOO tag, and we will have a much bigger mess. paul
Re: DOCBOOK: On the size of DocBook...
At 20:42 2002 09 06 +0900, Michael Smith wrote: Anyway, about the question at the end of number 3 above -- But what will that do to interchange? -- It seems like interchange isn't an issue if * the customized DTDs are strict subsets of the complete DTD * and users/user communities treat their customized DTDs as authoring DTDs and continue to use the full DTD for validation (that is, don't expect that DTDs that others interchange with their community will validate against their custom authoring-DTD subset) But that leads me to conclude you don't really want to change/subset the DTD, you just want some way to reduce the set a given author has to understand/work with. And I don't see that requirement as being addressed at the DTD level, I see it being addressed at the tool level and/or document/education level. paul
DOCBOOK: Re: On the size of DocBook...
/ Dave Pawson [EMAIL PROTECTED] was heard to say: | What impact might that have on the stylesheets Norm? | Divergent sets of stylesheets for pizza slices? No, no, no. You slice up the pie, you get a strict subset of the whole pie. The stylesheet for the whole pie can always be applied to the subset. | Picking up Pauls point, user demand is for 'less necessity' for | customisation, i.e. easier out of the box usage. It can't be quite that simple. DocBook works out of the box, no subsets required. Paul's other point, that this is a tools issue not a schema issue is compelling. Why is Simplified DocBook easier to use than full DocBook? 1. Because when you open the DTD in emacs and read the content models, it's smaller. 2. Because the user documentation for Simplified lists fewer elements. 3. Because when you pull down the what can I insert here list, it's shorter. 4. Because it's named Simplified, it's less intimidating. 5. ...? Options 3 and 4 seem most likely to me. Option 1 really requires making the schema smaller, but I can't imagine the set of people comfortable reading DocBook in the raw who are also disturbed by its size is very large. Option 2 could be created without changing the underlying schema. Option 3 could be solved with either a more sophisticated editing tool or by making the schema smaller. It may be that in the world of free tools, the latter is more practical than the former, but maybe that's not sufficient motivation to do the latter. Heck, maybe it means we'd all be better served by improving the docbook-ide mode for emacs than hacking subsets of the DTD. Option 4 is marketing. I don't understand marketing but it seems to work. At least that's what all the marketing folks keep assuring me. :-) | The stylesheets? I'd leave that to Norm. I have a nasty feeling | they *could* ride such a divide? In theory, the templates for elements not in your subset could be removed from the stylesheet. But that isn't as straightforward as it seems. And it's not clear that the simplified stylesheet is any simpler in practical terms. So, no, I don't think that's feasible. Be seeing you, norm -- Norman Walsh [EMAIL PROTECTED] | If a little knowledge is http://www.oasis-open.org/docbook/ | dangerous, where is the man who Chair, DocBook Technical Committee | has so much as to be out of | danger?--T. H. Huxley
Re: DOCBOOK: Re: On the size of DocBook...
On Fri, Sep 06, 2002 at 03:24:09PM -0400, Norman Walsh wrote: Why is Simplified DocBook easier to use than full DocBook? 1. Because when you open the DTD in emacs and read the content models, it's smaller. 2. Because the user documentation for Simplified lists fewer elements. 3. Because when you pull down the what can I insert here list, it's shorter. 4. Because it's named Simplified, it's less intimidating. 5. ...? Options 3 and 4 seem most likely to me. Option 1 really requires making the schema smaller, but I can't imagine the set of people comfortable reading DocBook in the raw who are also disturbed by its size is very large. That's a tautology: people who are using the 400-element DocBook DTD aren't put off by the fact that it's a 400-element DTD. There are many people out there who aren't using DocBook, and it's important to understand why. That it takes 650 pages to describe is rather intimidating. That there are elements like errorcode and calloutlist doesn't help someone trying to write an article, or a simple HOWTO structured as a book. I've tried to introduce DocBook in a handful of organizations. The TDG made it somewhat easier (it *must* be real; there's an O'Reilly book about it). But in the end, I've seen a lot of efforts fail because using DocBook only seems to work for people who have decided that learning how to use the DTD and tools is eventually better than the alternatives, despite the initial pain. Just for kicks, how difficult would it be to refactor DocBook into a simple core (based on Simplified DocBook, or the moral equivalent), and implement the full DTD as multiple layers of customizations on top of the simpler core? Once that's done, then it's easier[*] to consider adding more elements in the DTD: a simple core plus the required extra layers plus a few more elements, vs. a huge core plus a few extra elements. Z. *: easier from the user perspective, not from the DTD maintainer/tool writer's perspective.
Re: DOCBOOK: Re: On the size of DocBook...
Adam Turoff wrote: On Fri, Sep 06, 2002 at 03:24:09PM -0400, Norman Walsh wrote: Compelling anecdotal stuff about trying to introduce DocBook to new users snipped out./ Just for kicks, how difficult would it be to refactor DocBook into a simple core (based on Simplified DocBook, or the moral equivalent), and implement the full DTD as multiple layers of customizations on top of the simpler core? Once that's done, then it's easier[*] to consider adding more elements in the DTD: a simple core plus the required extra layers plus a few more elements, vs. a huge core plus a few extra elements. Yes! I think this is a good question and an excellent way of describing a valid way of looking at the result of the work. ...edN
DOCBOOK: Re: On the size of DocBook...
/ Adam Turoff [EMAIL PROTECTED] was heard to say: [...] Taking things slightly out of order... | Just for kicks, how difficult would it be to refactor DocBook into | a simple core (based on Simplified DocBook, or the moral equivalent), | and implement the full DTD as multiple layers of customizations on Quite. Hard that is. And it would introduce N! different DocBooks. How easy would that be to explain? | fail because using DocBook only seems to work for people who have | decided that learning how to use the DTD and tools is eventually | better than the alternatives, despite the initial pain. Would the learning curve for DocBook Core + DocBook Dublin Core + DocBook Unix really have a significantly gentler slope? Aren't the really hard issues editorial? Learning how to do structured authoring is hard. I suggest that it's possible that learning how to do structured authoring with a big DTD is only incrementally more difficult than learning how to do it with a small DTD. Be seeing you, norm -- Norman Walsh [EMAIL PROTECTED] | Perhaps, but let's not get bogged http://www.oasis-open.org/docbook/ | down in semantics.--Homer J. Chair, DocBook Technical Committee | Simpson, BABF07
DOCBOOK: Re: On the size of DocBook...
On Fri, Sep 06, 2002 at 05:14:18PM -0400, Norman Walsh wrote: / Adam Turoff [EMAIL PROTECTED] was heard to say: | Just for kicks, how difficult would it be to refactor DocBook into | a simple core (based on Simplified DocBook, or the moral equivalent), | and implement the full DTD as multiple layers of customizations on Quite. Hard that is. And it would introduce N! different DocBooks. How easy would that be to explain? I thought it would be difficult. How would I explain N! DocBook DTDs? Well, they're all subsets of the main DocBook DTD. :-) How difficult would it be to do that work conceptually, without going through the exercise creating DTDs, as customization layers or otherwise? I suspect it wouldn't be difficult at all. Most of that work is already done in TDG. Identifying the most important core 25-50 elements might be a little tricky, but identifying the 25-50 related tag groups (gui..., func...) shouldn't be *that* hard. :-) Basically, there are a bunch of people who understand HTML and the idea behind XML that still find the concepts behind DocBook too daunting. Figuring out how to subset DocBook is key. I think RSS 1.0 is on to something with a simple core and a series of extension modules (groups of related tags). | fail because using DocBook only seems to work for people who have | decided that learning how to use the DTD and tools is eventually | better than the alternatives, despite the initial pain. Would the learning curve for DocBook Core + DocBook Dublin Core + DocBook Unix really have a significantly gentler slope? Aren't the really hard issues editorial? I'd submit that Core + DC + UNIX wouldn't be that difficult to learn. Most programming language introductions build on concentric layers of features. This kind of breakdown is somewhat similar. Also, it mimics RSS 1.0 (modulo RDF syntactic sugar): a small, simple core, with discrete groups of additional elements. Most of the hard issues *are* editorial. I don't use authoring tools, but I'd expect that someone who wants to use a particular 75 elements that describe the content in their document want to necessarily ignore the other 325 or so that aren't useful. (Is this similar to the TEI pizza cutter approach you wanted to avoid?) Learning how to do structured authoring is hard. I suggest that it's possible that learning how to do structured authoring with a big DTD is only incrementally more difficult than learning how to do it with a small DTD. I don't know about that. Structured authoring with a 14 element DTD doesn't really compare to structured authoring with a 100 or a 400 element DTD. People know how to use HTML now, and the good ideas behind XML are rather well entrenched. Z.
DOCBOOK: Re: On the size of DocBook...
/ Adam Turoff [EMAIL PROTECTED] was heard to say: |On Fri, Sep 06, 2002 at 05:14:18PM -0400, Norman Walsh wrote: | Quite. Hard that is. And it would introduce N! different DocBooks. | How easy would that be to explain? | |I thought it would be difficult. How would I explain N! DocBook DTDs? |Well, they're all subsets of the main DocBook DTD. :-) Suppose there are subsets A, B, and C of DocBook, D. You might want D A A + B A + C A + B + C B B + C C Actually, now that I consider more closely, I guess it's (N-1)! because if A is the core then we'd really get: A A + B A + C A + B + C it wouldn't make sense to have B or C w/o A and presumably D is A + B + C. | I suspect it wouldn't be difficult at all. Most of that work is | already done in TDG. Identifying the most important core 25-50 | elements might be a little tricky, I tried to identify the core 25-50 elements, I wound up with more than 100. Start with 'article' as the only root and give it a whirl. | but identifying the 25-50 related | tag groups (gui..., func...) shouldn't be *that* hard. :-) If the sets must be strictly non-overlapping, that's going to be tough. If they're allowed to overlap, that's harder to customize. | | Basically, there are a bunch of people who understand HTML and the | idea behind XML that still find the concepts behind DocBook too | daunting. Which concepts of DocBook would be made simpler by the modularity you suggest? | Most of the hard issues *are* editorial. I don't use authoring | tools, but I'd expect that someone who wants to use a particular | 75 elements that describe the content in their document want to | necessarily ignore the other 325 or so that aren't useful. How does having them in the DTD have any bearing, though? | I don't know about that. Structured authoring with a 14 element DTD | doesn't really compare to structured authoring with a 100 or a 400 | element DTD. People know how to use HTML now, and the good ideas behind | XML are rather well entrenched. HTML has a good deal more than 14 elements, even if most people don't use most of them. Which is sort of the point, I think. Be seeing you, norm -- Norman Walsh [EMAIL PROTECTED] | There is no spoon. http://www.oasis-open.org/docbook/ | Chair, DocBook Technical Committee |
Re: DOCBOOK: Re: On the size of DocBook...
At 22:14 06/09/2002, Norman Walsh wrote: / Adam Turoff [EMAIL PROTECTED] was heard to say: [...] Taking things slightly out of order... | Just for kicks, how difficult would it be to refactor DocBook into | a simple core (based on Simplified DocBook, or the moral equivalent), | and implement the full DTD as multiple layers of customizations on Quite. Hard that is. And it would introduce N! different DocBooks. How easy would that be to explain? I don't see it like that Norm. I learn the basics (simplified). Then I need X layer/customisation, so I have to learn some percentage of an additional layer of tags, in which I must have interest, else I wouldn't bother? You don't eat the chocolate cake whole, you do it in bytes :-) Would the learning curve for DocBook Core + DocBook Dublin Core + DocBook Unix really have a significantly gentler slope? Yes, because its likely to be done over time. I want to see it working at first (I don't believe it), so I keep to simplified. ONly when my confidence grows do I chance using XML tagger 'chunk'. Then, later, I need some OO markup or whatever. By now I know how to 'add' a chunk, and my confidence has grown again. Its in the head, not the tools. Aren't the really hard issues editorial? Learning how to do structured authoring is hard. I suggest that it's possible that learning how to do structured authoring with a big DTD is only incrementally more difficult than learning how to do it with a small DTD. Seperable, IMO. its a mindset thing, hard with ten tags, another layer of difficulty if faced with 100? Regards DaveP
Re: DOCBOOK: Re: On the size of DocBook...
At 00:03 07/09/2002, Norman Walsh wrote: | I suspect it wouldn't be difficult at all. Most of that work is | already done in TDG. Identifying the most important core 25-50 | elements might be a little tricky, I tried to identify the core 25-50 elements, I wound up with more than 100. Start with 'article' as the only root and give it a whirl. Which 'head' did you have on Norm? tdg author? TC chair? Going back to your earlier point about getting used to structured markup, put on a Word users head (OK, hat). OK article as root. Major chunks. sect1..3 would do. major blocks title, para, two lists and literallayout inlines emph, internal, external links Remember what this word guy is trying to do. Get used to structured markup. With the above its possible to teach the basics. Not 100. (Chances are that with not much more than that, you'd have covered 70% of my use of docbook markup). I'm not a Unix manual writer, I'm learning to use XML. Thats sufficient to 'get into docbook'. Semantic markup comes later! HTML has a good deal more than 14 elements, even if most people don't use most of them. Which is sort of the point, I think. Exactly. I've said enough now, I think I'm harping on. regards DaveP
