cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simone Gianni <s.gia...@thebug.it>
Subject Re: ApacheCon Hackaton: focus on 2.2? - Documentation
Date Fri, 12 May 2006 12:13:12 GMT
Hi Carsten,
there is a lot of work that can be done offline: the current
documentation supports a doclet system with which the "short
description" part of components and some other informations can be
written directly inside the .java files. See
http://cocoon.zones.apache.org/daisy/documentation/g2/1066.html for details.

For non-component docs, I've edited some documents offline (like the
cform CSS document), simply editing a text file and then formatting it
on daisy. It's not the best way of doing it, surely, but it takes 5
minutes to format it. One annoying thing is that pasting a document in
WYSIWYG can duplicate some line brakes, and you don't notice this (cause
it's not a problem in HTML to have double line brakes) until you apply
<pre> formatting.

In the last document i wrote offline (fi:group documentation), I used
light HTML (pre, h1 and h2, b only) and then pasted it in HTML source
editor in daisy, and it worked smoothly. Then revised it in the WYSIWYG
editor, mainly to add a couple of links.

Apparently, in a common doc, the following HTML element can be used
without any problems (many others apply, but these are basically all you
need) :
- <p>
- <h1> rendered as green titles in WYSIWYG
- <h2> rendered as a bold title with a brown underline
- <h3> renderd as bold text
- <h4> <h5> <h6> are supported.
- <tt> for code keyworks inline
- <pre> for code blocks, rendered monospaced, gray background
- <ul><li> / <ol><li>
- <table><tbody><tr><td>/<th> (note that <thead> is not
used by WYSIWYG
editor, th are placed directly in tbody/tr)
- entities are HTML, so &nbsp; &agrave; etc..
- <a href="daisy:xxx"> where XXX is the document id. If you know you
will have to link to some docs, you could use this, but maybe editing
links directly from daisy is by far easier and safer.
- <img src="daisy:xxx"> same as links, but evend more dangerous.

To see them in a WYSIWYG editor, you can download the CSS from here
http://cocoon.zones.apache.org/daisy/resources/skins/default/css/default.css
. If you look at it, you can see all the other special formatting
(styles for comments, book lists, etc..).

Simone




Carsten Ziegeler wrote:

>hepabolu wrote:
>  
>
>>Carsten Ziegeler said the following on 11-05-2006 17:57:
>>    
>>
>>>the ugly or boring stuff. A simple example is documentation, but there
>>>      
>>>
>>Guys,
>>
>>I wholeheartedly agree that documentation needs to be tackled. 
>>    
>>
>Just to be clear, my statement was not targeted at anyone specific but
>at the whole community including myself. For example, I promised more
>docs about the portal months ago but just failed to provide them :(
>
>  
>
>>In the meantime Simone and I have/had some discussions offlist about the 
>>structure of the documentation. His ideas sound good and I prefer actual 
>>work done to a long discussion to reach consensus on the best structure. 
>>So I suggest that we give Simone some time to flesh out his ideas in Daisy.
>>My intention is to get pages with short descriptions of what should be 
>>in there so that others can jump in and replace the description with 
>>actual content. I believe it's much easier to write documentation when 
>>you're triggered by a short summary.
>>    
>>
>Good idea!
>
>Now my biggest problem is offline editing? I asked this question some
>time ago but never got any helping answer. What is the best way to edit
>the docs offline?
>
>Carsten
>  
>
-- 
Simone Gianni

Mime
View raw message