Importing Jayasoft's Drupal docs

[easyproglife <ea...@gmail.com>]

Hi Xavier.

Do you think it is possible to import the current documentation of Ivy from
Jayasoft's Drupal system to the wiki?

The benefit would be easy update/enhance of the documentation by the
community without taking your time.

What do you think?

easyproglife

Re: Importing Jayasoft's Drupal docs

[Xavier Hanin <xa...@gmail.com>]

On 11/15/06, Steve Loughran <st...@apache.org> wrote:
>
> Xavier Hanin wrote:
>
> >
> >
> > A wiki is good, but it often lead to inconsistencies when everybody can
> > contribute. This is good for sharing ideas and community experience, but
> I
> > think the core documentation should be under control of the development
> > team. Moreover, being able to contribute patch to the documentation is a
> > must IMO (which wasn't the case so far). So using something like xdoc
> could
> > be a solution. But what I don't like with xdoc is that it takes time to
> > generate the documentation to view how it will actually look like.
>
>
> 1. I like docs you can take away with you on your laptop; wikis dont go
> offline properly.


+1

2. What is xdoc?


The format used by maven 1.x, still supported by maven 2:
http://maven.apache.org/guides/getting-started/index.html#How%20do%20I%20create%20documentation?


3. Have you had a look at forrest? We use it at work to create HTML+PDF
> docs, mostly with .sxw content.


I only tried once several years ago, and but quickly  give up because the
generation was taking too long on my machine. I'm really not keen of things
where you have to launch and then wait for a long generation step. But maybe
things have changed?

SXW is XML in a Zip file, so could be generated from XHTML source if
> need be.


Sounds interesting,  I should try to have a look to see how it could be
used.

Xavier

> Hence I have worked last month on something which could fit this need, at
> > least IMO. The idea is to write plain html, with a small header using
> > javascript to actually format the page. Thus the page is viewable as is
> > in a
> > browser with no generation, but handles some basic features such as
> > - a format a little easier to author than html (the same one as the one
> we
> > use in drupal so far, i.e. html + automatic line break + <code>
> recognition
> > (including < and > escaping), + automatic recognition of IVY-xxx as jira
> > links, and some other basic links recognition)
> > - a navigation tree,
> > - a template which can easily be changed without modifying all the html
> > files.
> >
> > What I've done is not fully working yet, I'll try to find time to make
> it
> > better and share with you how ivy doc could look like with this system,
> to
> > see if we can consider it as a solution or not.
> >
> > But maybe others already have ideas on the subject?
> >
> > Xavier
> >
> > What do you think?
> >>
> >> easyproglife
> >>
> >>
> >
>
>

Re: Importing Jayasoft's Drupal docs

[Steve Loughran <st...@apache.org>]

Xavier Hanin wrote:

> 
> 
> A wiki is good, but it often lead to inconsistencies when everybody can
> contribute. This is good for sharing ideas and community experience, but I
> think the core documentation should be under control of the development
> team. Moreover, being able to contribute patch to the documentation is a
> must IMO (which wasn't the case so far). So using something like xdoc could
> be a solution. But what I don't like with xdoc is that it takes time to
> generate the documentation to view how it will actually look like.


1. I like docs you can take away with you on your laptop; wikis dont go 
offline properly.

2. What is xdoc?

3. Have you had a look at forrest? We use it at work to create HTML+PDF 
docs, mostly with .sxw content.

SXW is XML in a Zip file, so could be generated from XHTML source if 
need be.

> Hence I have worked last month on something which could fit this need, at
> least IMO. The idea is to write plain html, with a small header using
> javascript to actually format the page. Thus the page is viewable as is 
> in a
> browser with no generation, but handles some basic features such as
> - a format a little easier to author than html (the same one as the one we
> use in drupal so far, i.e. html + automatic line break + <code> recognition
> (including < and > escaping), + automatic recognition of IVY-xxx as jira
> links, and some other basic links recognition)
> - a navigation tree,
> - a template which can easily be changed without modifying all the html
> files.
> 
> What I've done is not fully working yet, I'll try to find time to make it
> better and share with you how ivy doc could look like with this system, to
> see if we can consider it as a solution or not.
> 
> But maybe others already have ideas on the subject?
> 
> Xavier
> 
> What do you think?
>>
>> easyproglife
>>
>>
> 

Re: Importing Jayasoft's Drupal docs

[Xavier Hanin <xa...@gmail.com>]

On 11/15/06, easyproglife <ea...@gmail.com> wrote:
>
> Xavier,
>
> remember two good Ant features that could help:
> 1. XSLT (not really Ant feature but could be part of the build)
> 2. Token replacement using FilterReader and FilterChains.
>
> I don't really know how XDOC looks like. Can you please send me a little
> example?


http://maven.apache.org/maven-1.x/using/site.html

In addition, what formats Drupal can export to?


The most insteresting format can export to is drupal xml, which is a very
raw format, quite easy to process using xslt or simple xml parsing. The
export of the 1.4.1 documentation is already available here:
http://svn.jayasoft.org/ivy/trunk/src/doc/ivy-book.xml
http://svn.jayasoft.org/ivy/trunk/src/doc/ivy-raw-book.xml

The raw one is, well, raw, i.e. using one of the drupal input formats. The
format is quite simple, basically it's html with:
- line breaks converted to <br/>
- <code> </code> interpreted to render code, including < and > escaping
- some basic link and url recognition

The ivy-book.xml is already processed with this input format. It is used to
generate the offline documentation, using this ruby script:
http://svn.jayasoft.org/ivy/trunk/src/doc/dxml_to_html.rb

Thiis can be a good start to convert it to anything else. the main problem
is to choose to what we want to convert it. Thus we have to see the
advantages and drawbacks of possible solutions.

You don't have to do all the work yourself. I will be glad to contribute.


Great!

Just give me a clue what format Drupal can export to and what format you
> want the docs to be in.


It's not only what *I* want the format to be in, but what the community on
this list want it to be. I have some preferences but if everybody vote for
something else I'll be ok with it. I just want the choice to be made with
care, because writing documentation is not an exciting task, so we sholud
try to make it ass easy as possible.

I have some XSLT knowledge. I can also think about ideas how to do the
> migration. What I need is a few little examples.
>
> Of course I prefer separating the 'model' and the 'view' of the docs. I
> think we should keep the docs in kind of 'view-less' format (e.g. XML) and
> generate HTML only on-demand (automatically of course).


What I would like is something where the generation is not an extra step,
where you have to run an ant task for it, wait for the entire processing and
then see how it looks like. I also would like something where you could very
easily modify the documentation when you read it on your workstation, maybe
even without leaving your browser. That's what I'm trying to do with my
experiment of in browser generation. I've uploaded th work I've done "as
is", simply to better show what I'm thinking about. It still need polishing
and work to implement other features I would like to have (like an edit
button, which would open a textarea in which you could edit the doc and hit
save, then it saves the file on your disk, and all you have to do is just
commit your changes).

Here is the link:
- a simple page build with this framework:
http://xavier.hanin.free.fr/xooki/xooki.html
- to see the other files (the "framework"):
http://xavier.hanin.free.fr/xooki/

It's a quick rush, there is no license for now, but I plan to create a small
open source project for this framework.

Xavier

easyproglife.
>
>
> On 11/15/06, Xavier Hanin <xa...@gmail.com> wrote:
> >
> > On 11/15/06, easyproglife <ea...@gmail.com> wrote:
> > >
> > > Hi Xavier.
> > >
> > > Do you think it is possible to import the current documentation of Ivy
> > > from
> > > Jayasoft's Drupal system to the wiki?
> >
> >
> > I'm not sure how difficult it is, but I guess this is not
> straightforward.
> > Anyway, we will have to find a way to import the documentation in some
> > way,
> > so we'll have to choose one which:
> > - do not take too long to do (I'm not ready to spend hours manually
> > importing everything)
> > - will fit the needs of the project in the future
> >
> > The benefit would be easy update/enhance of the documentation by the
> > > community without taking your time.
> >
> >
> > A wiki is good, but it often lead to inconsistencies when everybody can
> > contribute. This is good for sharing ideas and community experience, but
> I
> > think the core documentation should be under control of the development
> > team. Moreover, being able to contribute patch to the documentation is a
> > must IMO (which wasn't the case so far). So using something like xdoc
> > could
> > be a solution. But what I don't like with xdoc is that it takes time to
> > generate the documentation to view how it will actually look like.
> >
> > Hence I have worked last month on something which could fit this need,
> at
> > least IMO. The idea is to write plain html, with a small header using
> > javascript to actually format the page. Thus the page is viewable as is
> in
> > a
> > browser with no generation, but handles some basic features such as
> > - a format a little easier to author than html (the same one as the one
> we
> > use in drupal so far, i.e. html + automatic line break + <code>
> > recognition
> > (including < and > escaping), + automatic recognition of IVY-xxx as jira
> > links, and some other basic links recognition)
> > - a navigation tree,
> > - a template which can easily be changed without modifying all the html
> > files.
> >
> > What I've done is not fully working yet, I'll try to find time to make
> it
> > better and share with you how ivy doc could look like with this system,
> to
> > see if we can consider it as a solution or not.
> >
> > But maybe others already have ideas on the subject?
> >
> > Xavier
> >
> > What do you think?
> > >
> > > easyproglife
> > >
> > >
> >
> >
>
>

Re: Importing Jayasoft's Drupal docs

[easyproglife <ea...@gmail.com>]

Xavier,

remember two good Ant features that could help:
1. XSLT (not really Ant feature but could be part of the build)
2. Token replacement using FilterReader and FilterChains.

I don't really know how XDOC looks like. Can you please send me a little
example?

In addition, what formats Drupal can export to?

You don't have to do all the work yourself. I will be glad to contribute.
Just give me a clue what format Drupal can export to and what format you
want the docs to be in.

I have some XSLT knowledge. I can also think about ideas how to do the
migration. What I need is a few little examples.

Of course I prefer separating the 'model' and the 'view' of the docs. I
think we should keep the docs in kind of 'view-less' format (e.g. XML) and
generate HTML only on-demand (automatically of course).

easyproglife.


On 11/15/06, Xavier Hanin <xa...@gmail.com> wrote:
>
> On 11/15/06, easyproglife <ea...@gmail.com> wrote:
> >
> > Hi Xavier.
> >
> > Do you think it is possible to import the current documentation of Ivy
> > from
> > Jayasoft's Drupal system to the wiki?
>
>
> I'm not sure how difficult it is, but I guess this is not straightforward.
> Anyway, we will have to find a way to import the documentation in some
> way,
> so we'll have to choose one which:
> - do not take too long to do (I'm not ready to spend hours manually
> importing everything)
> - will fit the needs of the project in the future
>
> The benefit would be easy update/enhance of the documentation by the
> > community without taking your time.
>
>
> A wiki is good, but it often lead to inconsistencies when everybody can
> contribute. This is good for sharing ideas and community experience, but I
> think the core documentation should be under control of the development
> team. Moreover, being able to contribute patch to the documentation is a
> must IMO (which wasn't the case so far). So using something like xdoc
> could
> be a solution. But what I don't like with xdoc is that it takes time to
> generate the documentation to view how it will actually look like.
>
> Hence I have worked last month on something which could fit this need, at
> least IMO. The idea is to write plain html, with a small header using
> javascript to actually format the page. Thus the page is viewable as is in
> a
> browser with no generation, but handles some basic features such as
> - a format a little easier to author than html (the same one as the one we
> use in drupal so far, i.e. html + automatic line break + <code>
> recognition
> (including < and > escaping), + automatic recognition of IVY-xxx as jira
> links, and some other basic links recognition)
> - a navigation tree,
> - a template which can easily be changed without modifying all the html
> files.
>
> What I've done is not fully working yet, I'll try to find time to make it
> better and share with you how ivy doc could look like with this system, to
> see if we can consider it as a solution or not.
>
> But maybe others already have ideas on the subject?
>
> Xavier
>
> What do you think?
> >
> > easyproglife
> >
> >
>
>

Re: Importing Jayasoft's Drupal docs

[Xavier Hanin <xa...@gmail.com>]

On 11/15/06, easyproglife <ea...@gmail.com> wrote:
>
> Hi Xavier.
>
> Do you think it is possible to import the current documentation of Ivy
> from
> Jayasoft's Drupal system to the wiki?


I'm not sure how difficult it is, but I guess this is not straightforward.
Anyway, we will have to find a way to import the documentation in some way,
so we'll have to choose one which:
- do not take too long to do (I'm not ready to spend hours manually
importing everything)
- will fit the needs of the project in the future

The benefit would be easy update/enhance of the documentation by the
> community without taking your time.


A wiki is good, but it often lead to inconsistencies when everybody can
contribute. This is good for sharing ideas and community experience, but I
think the core documentation should be under control of the development
team. Moreover, being able to contribute patch to the documentation is a
must IMO (which wasn't the case so far). So using something like xdoc could
be a solution. But what I don't like with xdoc is that it takes time to
generate the documentation to view how it will actually look like.

Hence I have worked last month on something which could fit this need, at
least IMO. The idea is to write plain html, with a small header using
javascript to actually format the page. Thus the page is viewable as is in a
browser with no generation, but handles some basic features such as
- a format a little easier to author than html (the same one as the one we
use in drupal so far, i.e. html + automatic line break + <code> recognition
(including < and > escaping), + automatic recognition of IVY-xxx as jira
links, and some other basic links recognition)
- a navigation tree,
- a template which can easily be changed without modifying all the html
files.

What I've done is not fully working yet, I'll try to find time to make it
better and share with you how ivy doc could look like with this system, to
see if we can consider it as a solution or not.

But maybe others already have ideas on the subject?

Xavier

What do you think?
>
> easyproglife
>
>