Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

Matthew East
Hi Philip,

On Thu, Apr 9, 2009 at 3:05 PM, Philip Olson <[hidden email]> wrote:

>> If you do know of solid tools that the team could use to improve its
>> toolchain, and have some concrete proposals to put forward that could
>> be evaluated, please put them forward.
>
> We suffered from this problem for awhile and ended up creating a new project
> out of it that only requires a recent version of PHP. Granted it only deals
> with the building aspect but it's great to say only PHP is needed instead of
> various boring tools like automake, openjade, xsltproc, etc. This tool also
> builds CHM and PDF.
>
> One goal is to make it generic enough to work on any DocBook project (and it
> sorta is) but currently it contains PHP.net specific elements. If you're
> interested in such a tool let me know and we'll use Ubuntu as a testbed for
> when we continue work on expanding its use for others, or simply try it out.
> Granted we designed it for DocBook 5 but DocBook 4 should work without too
> much trouble.
>
> The tool in question is called PhD: http://wiki.php.net/doc/phd

That does look quite cool. I think for building HTML in particular we
are likely to be heavily biased in favour of tools which exist in the
Ubuntu main repository, because we build HTML in our package
generation process, which happens in the automatic Ubuntu build
machines in Launchpad. Those machines can only use build tools which
are in the Ubuntu repository. What are the chances of your tool making
it into Ubuntu?

But the barrier to entry that has been mentioned isn't really in the
build process: contributors to the team don't need to know about
those. What we're looking for is an easier way for people to
contribute material to the xml documents, so a wiki->xml tool, or a
robust xml editor...

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

Dougie Richardson-2
That is quite cool, what I've been looking at is the feasibility of a
web based editing system.

When you consider it, the selection of tags required is generally
pretty low and there are plenty of good JavaScript WYSIWYG editors out
there. If we had a WYSIWYM editor.

For example:

1. Click New Article, a skeleton DocBook page is generated and the
display leaves markers for title and any other expected tags.
2. User writes their article and highlights text that should be a
title and gives it a depth. System generates the relevant DocBook from
the highlighted region.
3. User hits the validate button and gets a pass or a highlighted
error on screen.
4. User saves and submits.

Or:

1. User finds an error and goes to the web docs, finds the page and
clicks submit alteration.
2. Page opens the editor with the relevant XML file.
3. User edits it.
4. User validates it.
5. User hits submit, a patch is generated and sent to the mailing list.

I've been messing about with a few ways of doing this and think that
the liklihood of having a production system that can do everything
core members can do is way off. However for the two above scenarios,
given the limited number of tags required I think this is completely
feasible within this cycle.

Regards,

Dougie Richardson
http://www.lynxworks.eu/
[hidden email]

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

Mario Đanić
Perhaps this can fit the bill: http://www.kix.in/projects/beacon/ ?

Cheers,
M.

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

Dougie Richardson-2
Looks interesting, I'll git the source and have a play.

--
Regards,

Dougie Richardson
http://www.lynxworks.eu/
[hidden email]

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

philipo
In reply to this post by Matthew East

> On Thu, Apr 9, 2009 at 3:05 PM, Philip Olson <[hidden email]>  
> wrote:
>>> If you do know of solid tools that the team could use to improve its
>>> toolchain, and have some concrete proposals to put forward that  
>>> could
>>> be evaluated, please put them forward.
>>
>> We suffered from this problem for awhile and ended up creating a  
>> new project
>> out of it that only requires a recent version of PHP. Granted it  
>> only deals
>> with the building aspect but it's great to say only PHP is needed  
>> instead of
>> various boring tools like automake, openjade, xsltproc, etc. This  
>> tool also
>> builds CHM and PDF.
>>
>> One goal is to make it generic enough to work on any DocBook  
>> project (and it
>> sorta is) but currently it contains PHP.net specific elements. If  
>> you're
>> interested in such a tool let me know and we'll use Ubuntu as a  
>> testbed for
>> when we continue work on expanding its use for others, or simply  
>> try it out.
>> Granted we designed it for DocBook 5 but DocBook 4 should work  
>> without too
>> much trouble.
>>
>> The tool in question is called PhD: http://wiki.php.net/doc/phd
>
> That does look quite cool. I think for building HTML in particular we
> are likely to be heavily biased in favour of tools which exist in the
> Ubuntu main repository, because we build HTML in our package
> generation process, which happens in the automatic Ubuntu build
> machines in Launchpad. Those machines can only use build tools which
> are in the Ubuntu repository. What are the chances of your tool making
> it into Ubuntu?

Maybe after it's ready for better generic use which is something we're  
serious about and even have a GSoC student working on that this  
summer. But the license and code are open, there's nothing holding it  
back... except human time.

> But the barrier to entry that has been mentioned isn't really in the
> build process: contributors to the team don't need to know about
> those. What we're looking for is an easier way for people to
> contribute material to the xml documents, so a wiki->xml tool, or a
> robust xml editor...

We also suffer from that and researched options over the years but  
nothing felt right. So, we (especially Yannick) have started work on  
another project appropriately named 'doc-editor' that allows users to  
login, edit and commit to the DocBook. And it allows 'anonymous'  
people to submit to a patch queue for developers to review and commit.  
However, it's in alpha stages right now but if interested have a look  
at a fully functional demo:

   PHP Doc Editor (Anonymous CVS user: cvsread pass: phpfi)
   - http://ytorres.dyndns.org/doc-editor/

Please don't work it too hard though :) And it also has dreams of  
being generic enough to work outside the php.net realm, just look at  
its TODO file for details. Unfortunately we don't use po files for  
translations and are considering this but change can be difficult work.

Perhaps it would be enjoyable if both the PHP and Ubuntu projects  
worked on a single tool like this.

Regards,
Philip



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

Dougie Richardson-2
For anyone who wants to try Beacon, fill your boots - I've stuck it on
my home page:
http://www.lynxworks.eu/editor/

FWIW I think it's very promising.

Regards,

Dougie Richardson
http://www.lynxworks.eu/
[hidden email]

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

Nandeep Mali
In reply to this post by Matthew East
Hello,

I just came upon this when Mario (who has pointed out about Beacon
previously) pointed me here. I am the main active developer of Beacon
and its great to see community interest generating.

The project was in hibernation for few months and, as mentioned
before, time is the only thing holding us back. I have currently
restarted working on the code base so it can be useable by month end.
There is a plugin framework in the works (the GIT repository is
somewhat outdated currently, will update it soon). This framework
allows one to write a plugin for any XML based doc type (like
GuideXML, DocBook, etc) so the editor can be made to work easily with
them.

There is an interest in Fedora community as well in making it work for
Docbook and am currently working with another developer (who is
working on a Docbook plugin for Beacon) on this.

If you are interested in Beacon then you are welcome to hang out at
#beacon on Freenode. The project is far from /dev/null. :)

Kind Regards
Nandeep (n9986 on IRC)

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc