You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cocoon.apache.org by Ulrich Mayring <ul...@denic.de> on 2001/01/02 13:13:28 UTC
Documentation
Hi folks,
undoubtedly many of you have in the companies they work for the same
problem as the cocoon project: how to document code in a sensible way?
Of course we "XML people" think that documentation should be written in
XML and there should be a stylesheet to generate printable docs (e.g.
PDF via fop) and one for generating HTML docs for viewing online.
Now, I think we all agree that simply writing some kind of XML doesn't
really do the trick either, there should be a standard. That's why the
cocoon project uses StyleBook, which - correct me if I'm wrong - is a
tool for working with the DocBook DTD. The problem with DocBook is that
it is very complex and the problem with StyleBook is that is doesn't
work online.
We have now internally decided to evaluate XMetal as an editor for
writing docs and are now thinking about using the DocBook DTD with it.
My questions:
- does this combination make it easy enough to write docs, so that even
a lawyer or PR guy can use it?
- are there other editors comparable to XMetal, perhaps even OpenSource?
- which way is the cocoon project headed?
- are there any other ideas? Am I perhaps on the wrong track?
Ulrich
--
Ulrich Mayring
DENIC eG, Systementwicklung
Re: Sitmap question
Posted by Giacomo Pati <gi...@apache.org>.
Klaus Drechsler wrote:
>
> Hi,
>
> what does {1} stands for?
>
> For example:
>
> <map:generate src="docs/samples/sql/{1}.xml"/>
It stands for what the parent matcher has matched, ie:
<map:match pattern="myuri/*">
<map:generate src="docs/samples/sql/{1}.xml"/>
</map:match>
If the requested URI is "myuri/welcome" the {1} would stand for
"welcome" and the generate will get a src attribute with a value of
"docs/samples/sql/welcome.xml"
Giacomo
Re: Sitmap question
Posted by Paul Russell <pa...@luminas.co.uk>.
* Klaus Drechsler (drechsler@gmx.net) wrote :
> Hi,
> what does {1} stands for?
> For example:
> <map:generate src="docs/samples/sql/{1}.xml"/>
The {1} is replaced with the value matched in the surrounding
matcher(s). For example:
<map:match pattern="/foo/*">
<map:generate src="docs/foo-doc/{1}.xml"/>
<map:transform src="default.xsl"/>
<map:serialize/>
</map:match>
with a request for '/foo/bar' would generate from the file
'docs/foo-doc/bar.xml'. Does this help?
Paul
--
Paul Russell Email: paul@luminas.co.uk
Technical Director Tel: +44 (0)20 8553 6622
Luminas Internet Applications Fax: +44 (0)870 28 47489
This is not an official statement or order. Web: www.luminas.co.uk
Sitmap question
Posted by Klaus Drechsler <dr...@gmx.net>.
Hi,
what does {1} stands for?
For example:
<map:generate src="docs/samples/sql/{1}.xml"/>
Bye,
Klaus
--------------------------------------
Farewell! I will omit no opportunity
That may convey my greetings, love, to thee.
Romeo&Juliet
(Act III, Scene V)
--------------------------------------
PGP-Key: http://www.kdnet.de/pgp
Re: Documentation
Posted by Berin Loritsch <bl...@apache.org>.
I-Chung Young wrote:
> I don't know if this will help. How about simplified
> DocBook DTD from
> http://www.nwalsh.com/docbook/simple/index.html
>
> ------------
> I-Chung Young
> ichung@puma.mt.att.com
>
> On Wed, 3 Jan 2001, Ulrich Mayring wrote:
>
>
>> Berin Loritsch wrote:
>>
>>>> Yes ok, but which markup will it use? Is it going to be Stylebook forever
>>>> or are there grand new plans?
>>>
>>> It will use whatever you want it to use. It can even
>>> run DocBook for you--if your willing to wait.
>>
>> I don't quite get that - the docs for cocoon2 surely must be written in
>> some kind of markup?!?
The docs for Cocoon (both versions) are currently written in
StyleBook markup. AFAIK the plan is to use Cocoon to render
it's own docs once it is compiled. As such, the markup is not
limited to StyleBook.
Actually, the markup for the documents in StyleBook is fairly
flexible. I had to modify the DTD for Avalon when I was writing
the docs for that project--and everything worked well. StyleBook
has a markup for a book.xml file that must be followed. That
file is basically the spine for the list of docs to be generated.
Once StyleBook renders the individual docs, you have great
flexibility as to the actuall markup. It does generate some extra
markup so that you can render the menu along with every page--
keeping track of which page you are on.
At our InfoPlanning.com site, what we did to get around this, was
to include a file called menu.xml along with every rendered page
(in the stylesheet). The only issue with this approach is that
there is no easy way to determine which page we are on. If we
determined that the investment was worth it, we would have found
a way around it--but the graphical designer's vision of our site
didn't include special marking for which page the visitor is on,
so we didn't bother.
Re: Documentation
Posted by I-Chung Young <ic...@puma.mt.att.com>.
I don't know if this will help. How about simplified
DocBook DTD from
http://www.nwalsh.com/docbook/simple/index.html
------------
I-Chung Young
ichung@puma.mt.att.com
On Wed, 3 Jan 2001, Ulrich Mayring wrote:
> Berin Loritsch wrote:
> >
> > > Yes ok, but which markup will it use? Is it going to be Stylebook forever
> > > or are there grand new plans?
> >
> > It will use whatever you want it to use. It can even
> > run DocBook for you--if your willing to wait.
>
> I don't quite get that - the docs for cocoon2 surely must be written in
> some kind of markup?!?
>
> Ulrich
>
> --
> Ulrich Mayring
> DENIC eG, Systementwicklung
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-users-unsubscribe@xml.apache.org
> For additional commands, e-mail: cocoon-users-help@xml.apache.org
>
>
Re: Documentation
Posted by Ulrich Mayring <ul...@denic.de>.
Berin Loritsch wrote:
>
> > Yes ok, but which markup will it use? Is it going to be Stylebook forever
> > or are there grand new plans?
>
> It will use whatever you want it to use. It can even
> run DocBook for you--if your willing to wait.
I don't quite get that - the docs for cocoon2 surely must be written in
some kind of markup?!?
Ulrich
--
Ulrich Mayring
DENIC eG, Systementwicklung
Re: Documentation
Posted by Berin Loritsch <bl...@apache.org>.
Uli Mayring wrote:
> On Tue, 2 Jan 2001, Berin Loritsch wrote:
>
>
>> The editor approaches that ease of use you are looking for.
>> Out of all the editors I evaluated, it is the best--bar none.
>> Most of the other XML editors have a lot of catching up to do.
>> Again I would suggest either using a subset of DocBook, or
>> the StyleBook markup.
>
>
> Well I am currently using a home-brewn XML markup. If I were to use a
> home-brewn subset of DocBook I might as well keep my own creation, no? :)
True. Should there be something that is DocBook specific,
and your markup is a subset of DocBook, then you might be
able to take advantage of it. That's the only reason to
avoid your own markup.
If your own creation suits your needs (as most of them
do), then use what works for you. Unfortunately there
is no right answer. DocBook affords interchangeability,
and the ability to send the document source to someone
else and allow them to read it without altering their
tools.
>
>
>>> - which way is the cocoon project headed?
>>
>> That's a general question with a general answer. Cocoon 2
>> has both live generation and command line generation
>> capabilities. At this time, the live generation is much
>> more current and workable.
>
>
> Yes ok, but which markup will it use? Is it going to be Stylebook forever
> or are there grand new plans?
It will use whatever you want it to use. It can even
run DocBook for you--if your willing to wait.
Re: Documentation
Posted by Uli Mayring <ul...@denic.de>.
On Tue, 2 Jan 2001, Berin Loritsch wrote:
> The editor approaches that ease of use you are looking for.
> Out of all the editors I evaluated, it is the best--bar none.
> Most of the other XML editors have a lot of catching up to do.
> Again I would suggest either using a subset of DocBook, or
> the StyleBook markup.
Well I am currently using a home-brewn XML markup. If I were to use a
home-brewn subset of DocBook I might as well keep my own creation, no? :)
> > - which way is the cocoon project headed?
>
> That's a general question with a general answer. Cocoon 2
> has both live generation and command line generation
> capabilities. At this time, the live generation is much
> more current and workable.
Yes ok, but which markup will it use? Is it going to be Stylebook forever
or are there grand new plans?
Ulrich
Re: Documentation
Posted by Berin Loritsch <bl...@apache.org>.
Ulrich Mayring wrote:
> Hi folks,
>
> undoubtedly many of you have in the companies they work for the same
> problem as the cocoon project: how to document code in a sensible way?
> Of course we "XML people" think that documentation should be written in
> XML and there should be a stylesheet to generate printable docs (e.g.
> PDF via fop) and one for generating HTML docs for viewing online.
Ah, a subject near and dear to my heart.
> Now, I think we all agree that simply writing some kind of XML doesn't
> really do the trick either, there should be a standard. That's why the
> cocoon project uses StyleBook, which - correct me if I'm wrong - is a
> tool for working with the DocBook DTD. The problem with DocBook is that
> it is very complex and the problem with StyleBook is that is doesn't
> work online.
You are correct in stating that there should be a standard.
As to your assumption about StyleBook, let me correct you:
it is DocBook like meaning that it is not interchangable.
You are correct in both of your conclusions in the last
sentence. The main difference is that you can use the
Stylebook markup and Cocoon to generate the docs. In fact,
that is what we did at http://www.infoplanning.com. A
word of caution: the entities described in the DTD don't
get properly translated to netscape clients.
> We have now internally decided to evaluate XMetal as an editor for
> writing docs and are now thinking about using the DocBook DTD with it.
You will find XMetal to be an excellent editor. You will
find that you would be better to define a subset of
DocBook that is more limited in your choices of construction.
That way you will be able to have sane XSL stylesheets.
Norman Walsh (http://www.nwalsh.com) has some comprehensive
stylesheets for DocBook. You will find them unsuitable
for live transformation. It takes 5-7 seconds for the
stylesheet to be read and created, and up to a minute for
the document to be constructed.
> My questions:
>
> - does this combination make it easy enough to write docs, so that even
> a lawyer or PR guy can use it?
The editor approaches that ease of use you are looking for.
Out of all the editors I evaluated, it is the best--bar none.
Most of the other XML editors have a lot of catching up to do.
Again I would suggest either using a subset of DocBook, or
the StyleBook markup.
> - are there other editors comparable to XMetal, perhaps even OpenSource?
I have looked and looked. Unfortunately, I have not found
anything as easy to use. If you are comfortable with the
markup itself, Allaire's HomeSite tool is excellent.
> - which way is the cocoon project headed?
That's a general question with a general answer. Cocoon 2
has both live generation and command line generation
capabilities. At this time, the live generation is much
more current and workable.
> - are there any other ideas? Am I perhaps on the wrong track?
I have come to the conclusion that DocBook, while a great
and mature standard, is too complex for web enabled
environments. Take a subset of the DocBook definition
that has the features of StyleBook (otherwise you will
limit yourself too much).
DocBook was written initially as an SGML based markup,
with static generation tools. In this role, it performs
very well. In a more dynamic role, it is too complex.
Perhaps when computers can transform the entire DocBook
stylesheets in less than a second it won't be an issue.
>
> Ulrich