DOCBOOK: Re: Markup for exercises
Sounds like fair comments. Given that there are DTDs around that deal specifically with Training & Courseware I guess users that opt for Docbook should be content with a more generalised approach. Discussions so far have shown you're right about spawning more requests for flexibility (I've seen about 4 models so far) so a more generalised approach _would_ be more suitable. I have to say that in the documents I've created so far, I've been quite happy with the existing elements and using a to nest them in. It would, however, be more helpful to allow specifically and nesting s seems better than the s I've used in the past. Does it need to be ? Wouldn't just work too? Mart -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 / [EMAIL PROTECTED] was heard to say: | There seems to be a rough consensus on this now. What's the next step? I think we need to see some more explicit description of the semantics and content models. | Am Samstag, 12. Oktober 2002 12:13 schrieb [EMAIL PROTECTED]: |> |> ...as in sectioninfo... |> ...information on what is needed to setup the exercise, |> student data etc... |> ... |> |> ... |> ... |> |> |> ... |> ... |> |> ... |> I'm personally quite unhappy with this proposal as it's written. It adds five fairly general sounding element names (setup, scenario, task, objective, and solution) in a fairly narrow context. Experience suggests that this is too specific; it will work for some people, but it will spawn frequent requests for more flexibility and new special-purpose elements. I'd be happier with a structure like this: ... Setup... Scenario... Task Objective Solution I'm not sure I like the element name "exercisesection" very much, but you see what I have in mind. We have had some discussion of adding a floating section-like element, "topic". If we did that, then we might allow exercises to contain topics. |> Some method of controlling Stylesheets would be required to enable | authors |> to display s or not depending on the documentation required. | For |> example, a Student version of the document might not contain s |> whereas the Tutor version of the document would contain everything. | | That would be really great! The goal in designing the markup is to make sure that the structure contains enough information to drive the presentation you want. Be seeing you, norm
Re: DOCBOOK: Re: Markup for exercises
Norm There seems to be a rough consensus on this now. What's the next step? Mart Am Samstag, 12. Oktober 2002 12:13 schrieb [EMAIL PROTECTED]: > > ...as in sectioninfo... > ...information on what is needed to setup the exercise, > student data etc... > ... > > ... > ... > > > ... > ... > > ... > This structure makes complete sense to me. The term is much better than . In an you can also say "Answer the following questions" and than just use an OrderedList. And so you can do in the corresponding . > > Some method of controlling Stylesheets would be required to enable authors > to display s or not depending on the documentation required. For > example, a Student version of the document might not contain s > whereas the Tutor version of the document would contain everything. That would be really great! Joachim
Re: DOCBOOK: Re: Markup for exercises
> > ...as in sectioninfo... > ...information on what is needed to setup the exercise, > student data etc... > ... > ... > ... > > ... >> Therefore s and s should be allowed to appear in >> and , respectively. An should only be allowed when the >> has had a . Unfortunately, this dependency is not >> context-free and therefore not expressible in a DTD. Sure. Assuming that a must actually be a question and is actually an answer to that question ( can do that job). Perhaps we should think of these tags at a higher level. ie. contains the objective of the exercise - which could be a question or it could be a task - whichever way is interpreted, would contain the solution. Maybe it's as easy as saying the tag names should be and ? Actually, thinking about it, wouldn't work as you'd need it's and elements seperated... I don't like this approach, it's too rigid. Another complication is that an exercise may be more than one objective. Subsequent objectives might rely on the success of the previous objective. ie. 1. Write a program that outputs "Hello World" 2. Modify the program to make "Hello" blue and "World" red 3. Make the red "World" flash Perhaps an element structure similar to (called here) could be used to create: ...as in sectioninfo... ...information on what is needed to setup the exercise, student data etc... ... ... ... ... ... ... Some method of controlling Stylesheets would be required to enable authors to display s or not depending on the documentation required. For example, a Student version of the document might not contain s whereas the Tutor version of the document would contain everything. Mart
Re: DOCBOOK: Re: Markup for exercises
>> I think I like the idea of containment better than ID/IDREF for >> associating exercises and solutions. >> >> Would this work? >> >> >> ... >> ... >> I tend to agree. Such a structure would be useful to me too. Perhaps these might be useful? (or something similar)... ...as in sectioninfo... ...information on what is needed to setup the exercise, student data etc... ... ... ... The effect of & could be built manually using & etc. if such elements were allowed directly in which I think would help fend off the recent list comments regarding bloat... Mart
DOCBOOK: Upcast to Docbook?
Hi there Has anyone done any work on stylesheets to transform the XML results for the RTF to XML converter called Upcast? Upcast seems to create a better XML structure from my Word docs than (say) Logictran & Majix has but it has it's own Generic DTD - I'd rather not re-invent the wheel if possible. TIA. Mart
DOCBOOK: Re: Forcing a Line Feed
Norm >>/ Martin Gautier <[EMAIL PROTECTED]> was heard to say: >>| I want to be able to do the thing in a . ie. Force a line feed >>| within my paragraph. >>| >>| eg. Here is my paragraph and this is an >>| ...and now I want this on a >>| new line after the image which must be in-line >> >>Why do you want to do this? What is the significance of the newline >>after the image? There are a number of reasons this might happen, not necessarily with the element ( containing lines longer than the width of my publishing media for example). In my example, if the was inside a , there might not be enough room in the cell to present the paragraph as expected - It would be convenient to force a line break at a suitable (for presentation purposes) location decided by me rather than my stylesheet. When I posed the question I expected a reply describing something I missed along the lines of using an or - both elements designed for presentation rather than data description. I guess there isn't such a thing :o( Perhaps I need to study my stylesheets and possibly modify them to build a solution for me - something I was hoping to avoid. Thanks for giving this some attention... Mart
DOCBOOK: Forcing a Line Feed
I wonder if anyone can offer a solution to this problem? Normally, to get text on a new line I'd write the following This is on line 1 This is on the next line down As Norm has recognised (and described in the description for in DB:TDG), it is sometimes necessary to force a line feed explicitly to guarantee correct formatting. To this end, the tag is available as a child in some elements. I want to be able to do the thing in a . ie. Force a line feed within my paragraph. eg. Here is my paragraph and this is an ...and now I want this on a new line after the image which must be in-line I've looked at using one of the standard entity refs but there isn't a &lf; (or whatever it might be called) though this would seem the most reasonable approach. eg. Here is my paragraph and this is an ...&lf;and now I want this on a new line after the image which must be in-line Any ideas? TIA Mart
Re: DOCBOOK: A straw proposal for help topics in DocBook
DOH! Of course it does. Sorry chaps. That'll work fine for me... Mart I wrote: > >>|So it looks like if we use a Section-like (instead of Chapter-like) > >>|content model for Topic, it'll mean that Topics can contain only > >>|recursive Sections, not numbered ones (Sect1-Sect5), and that > >>|Topics can't contain Refentrys at all (or Simplesect). Norm wrote: > >>I am strongly opposed to allowing Topics to contain any form of > >>sectioning element. They are not part of the sectioning hierarchy, > >>that's one of the main motivations for creating them (IMHO). Martin wrote: > There's some logic there but it would certainly be useful to support some > sort of sort of container(s) within to allow us to seperate out > the topic content. But the content model Norm proposed for Topic is recursive, just like the one for Section is -- that is, a Topic can contain other Topics, nested indefinitely. So you could do: How to Drive Start to start your car you use your keys to switch on the engine to make your car go ... Martin Gautier Technology Consultant Myrnham Associates Ph: 0709 2234 228 Fax: 0702 0967 322 email: [EMAIL PROTECTED] Web: http://www.myrnham.co.uk/ Michael Smith <[EMAIL PROTECTED]> 18/10/01 06:00 To: [EMAIL PROTECTED] cc: Subject:Re: DOCBOOK: A straw proposal for help topics in DocBook I wrote: > >>|So it looks like if we use a Section-like (instead of Chapter-like) > >>|content model for Topic, it'll mean that Topics can contain only > >>|recursive Sections, not numbered ones (Sect1-Sect5), and that > >>|Topics can't contain Refentrys at all (or Simplesect). Norm wrote: > >>I am strongly opposed to allowing Topics to contain any form of > >>sectioning element. They are not part of the sectioning hierarchy, > >>that's one of the main motivations for creating them (IMHO). Martin wrote: > There's some logic there but it would certainly be useful to support some > sort of sort of container(s) within to allow us to seperate out > the topic content. But the content model Norm proposed for Topic is recursive, just like the one for Section is -- that is, a Topic can contain other Topics, nested indefinitely. So you could do: How to Drive Start to start your car you use your keys to switch on the engine to make your car go ... To subscribe or unsubscribe from this elist use the subscription manager: <http://lists.oasis-open.org/ob/adm.pl> To subscribe or unsubscribe from this elist use the subscription manager: <http://lists.oasis-open.org/ob/adm.pl>
Re: DOCBOOK: A straw proposal for help topics in DocBook
>>|So it looks like if we use a Section-like (instead of Chapter-like) >>|content model for Topic, it'll mean that Topics can contain only >>|recursive Sections, not numbered ones (Sect1-Sect5), and that >>|Topics can't contain Refentrys at all (or Simplesect). >>I am strongly opposed to allowing Topics to contain any form of >>sectioning element. They are not part of the sectioning hierarchy, >>that's one of the main motivations for creating them (IMHO). There's some logic there but it would certainly be useful to support some sort of sort of container(s) within to allow us to seperate out the topic content. For example, a topic on "How to start your car" might contain a discussion on what the engine is, why it needs to be running and what equipment is required to start the car (the keys), this discussion might be followed by a procedure listing the steps taken to start the car (put the keys in, gearshift in neutral, turn the key etc.). The element exists but not a type element. I currently use the following syntax for such documentation: How to Drive Start to start your car you use your keys to switch on the engine to make your car go put your keys in the ignition check the gearshift is in neutral turn the key ... ... Mart Martin Gautier Technology Consultant Myrnham Associates Ph: 0709 2234 228 Fax: 0702 0967 322 email: [EMAIL PROTECTED] Web: http://www.myrnham.co.uk/ To subscribe or unsubscribe from this elist use the subscription manager: <http://lists.oasis-open.org/ob/adm.pl>
Re: DOCBOOK: A couple of questions... DocBook's basics anddocumentation
Andrew Check out http://www.xml.com for tutorials on starting out with XML. Once you have a handle on that, there's a tutorial called "Writing Documentation Using DocBook" by David Rugge, Mark Galassi & Eric Bischoff on the 'net somewhere - a search on Google should track it down if it's not at http://www.caldera.de/~eric/crash_course/HTML/index.htm. As an XML/DocBook application programmer myself, I found the free download of "Docbook: The Definitive Guide" published by O'Reilly (http://www.oreilly.com/catalog/docbook/) very useful - http://docbook.org/tdg/en/. Hope that helps. On a personal note, what platform will you be developing for (Win/Linux)? What development tools will you be using? Mart ________ Martin Gautier Technology Consultant Myrnham Associates Ph: 0709 2234 228 Fax: 0702 0967 322 email: [EMAIL PROTECTED] Web: http://www.myrnham.co.uk/ The DeerBear <[EMAIL PROTECTED]> 16/09/01 16:39 To: Mailing List DocBook <[EMAIL PROTECTED]> cc: Subject: DOCBOOK: A couple of questions... DocBook's basics and documentation Hello everybody, With the occasion of this first message I introduce myself. My name is Andrew and I am a programmer. I've been asked to write a docbook visual editor( that may become open-source ) but I never dealt with XML before so... would you please point me to a *good* basic documentation that will allow me to get acquainted with these things quickly? Hoping in your ( possibly in english please ) answers, I greet you people warmly. Best Regards, Andrew To subscribe or unsubscribe from this elist use the subscription manager:
