Hi guys,
Back again on this topic...
One very important point, IMO, is being able to reuse parts of the
documentation for different purpose, in terms of content or publishing
media. For instance, "jallib an introduction" could be seen as (it's just an
example)
jallib_an_introduction (kind of TOC)
- jalv2 introduction
- jallib concepts
- peripherals
- PWM
- theory
- tutorial (practice)
- ADC
- theory
- tutorial (practice)
...
>From this, I want to build a PDF, and HTML (publishing media), as a whole.
But, also, I want to extract the tutorial parts and upload to our website
(variable content). And I want this to be scriptable, with automation,
auto-upload, etc... (so more work buildbot -- or Bee), just like jal code.
This is about integrating tutorials on jalliblog into a more general
document. But just like code, when I update a tutorial, I don't want (and
won't) to update every documents out there using this tutorial. One source
of information, many outputs.
With approach using Word & "friends", it seems impossible (right ?). That's
why I'm trying to find the right tool, flexible enough, easy enough to use.
Not that easy.
>From the documentation tools used, there seems to be two main actors:
Docbook, and DITA. Docbook seems nice but reuse if not that easy (it's made
for book, a big static content). I had a look at DITA, which is actually
designed for reuse (see this 5-minutes tutorial explaining DITA concepts:
http://dita.xml.org/5-minute-dita-tutorial). I think it may worth it (is it
English ?) to give a try...
About GUI, since it's XML, every XML editor can be used. I tried XXE from
XMLMind (http://www.xmlmind.com/xmleditor/).
What's your point on this ? Do you understand the need and agree ? What
other solutions can you see ?
We need to decide something on this topic, which is an important one. One
decision being: "postpone"...
Cheers,
Seb
--
Sébastien Lelong
http://www.sirloon.net
http://sirbot.org
2009/8/24 Sebastien Lelong <[email protected]>
> Hi,
>
> I understand Lyx as being a layer over LaTEX. Maybe "just" a GUI. What I
> don't like with LaTEX is, by default, it produces document with quite ugly
> police, old-style HTML, etc... Every time I open pjal manual, my first
> thoughts are: "it's ugly, I don't want to read, looks old, looks like a
> thesis"... But typography is just perfect. But not sexy.
>
> About ASCIIDOC, my recent tries tend to show it probably will be too
> complicated. Dealing with tables sometime works, sometime won't.
>
> I may give another try with Docbook, being the reference in documentation
> writing (with LaTEX). I've found this GUI:
> http://www.xmlmind.com/xmleditor/ . Works nice, available on all platforms
> (java). Docbook also requires some customization, but we may be able to take
> one and adapt it to jallib. Ex: gnome project has its doc written with
> docbook, we could use their stylesheets.
>
> Now it may seem a little bit overkill for a project like jallib (like SVN
> was overkill ?...). Should we go this way ? I tend to say "yes", but I also
> know it won't succeed without agreement of all of us.
>
>
> Please advise !
>
>
> Cheers,
> Seb
> --
> Sébastien Lelong
> http://www.sirloon.net
> http://sirbot.org
>
>
> 2009/8/23 Joep Suijs <[email protected]>
>
>
>> maybe openoffice is an altenative in the way it is open source. ;ynx
>> should also be on the list. The pjal doc is written in it. ( gave it a
>> try but until now, i find it hard to use and can't find some functions
>> (although i can't imagine they are not supported).
>> Joep
>>
>> 2009/8/21, Sebastien Lelong <[email protected]>:
>> > Hi,
>> >
>> > OpenOffice could be an option but have the same problem as Word:
>> >
>> > 1. personal taste: same issue as Word, I don't like triggering a big
>> tool
>> > just to fix few typos for instance.
>> > 2. consistent output: many people (I hope...) will enrich this
>> document.
>> > How to make sure we'll have the same consistent output with tools like
>> OO or
>> > Word ? Correctly use styles ? Will this be enough ? Will we be able to
>> keep
>> > a professional (or high quality) looking documentation ?
>> > 3. important point is to be able to put in under SVN so we can see
>> > differences between two versions, what's been added in the local copy,
>> ...
>> > just like code. Word as OO docs are imported as binary format, and SVN
>> won't
>> > show any diff on it (just an "something has changed..."). How to make
>> sure
>> > someone didn't change something unexpectidely ?
>> > 4. how to (easily) script documentation processing ? When original doc
>> > source is in format like LaTEX, Docbook or ASCIIDOC, you can make it
>> built,
>> > checked and produce output automatically.
>> >
>> >
>> > Cheers,
>> > Seb
>> >
>> >
>> >
>> >>
>> >> I don't understand why not OpenOffice.org doc? It can export also in
>> >> HTML/XHTML, PDF, MediaWiki txt, BibTeX, LaTeX 2e and is ported on all
>> >> operating systems. It can save also in MS Word format, and many
>> >> others.
>> >>
>> >> ------------------
>> >> Vasi (http://moriscanet.blogspot.com)
>> >>
>> >> On Aug 21, 3:52 pm, Sebastien Lelong <[email protected]>
>> >> wrote:
>> >> > Hi guys,
>> >> >
>> >> > You've probably heard about documentation issues these last weeks.
>> Toon
>> >> and
>> >> > Joep started to write a "jalv2 & jallib - an introduction" document.
>> As
>> >> > a
>> >> > Word file. First drafts clearly show interests for this kind of
>> >> > documentation, but there are lots of other source of information
>> which
>> >> could
>> >> > be used to enrich it, like some blog posts.
>> >> >
>> >> > Maybe it's time to normalize this and provide a common way to produce
>> >> this
>> >> > kind of documentation. One important aspect is it must be under SVN.
>> Not
>> >> > only the file, but also the content. SVN should be able to deal with
>> >> > documentation as it does for the code, namely documentation should be
>> in
>> >> > text format. It also shouldn't a pain fixing just a typo, so not
>> having
>> >> > a
>> >> > turn on Word would really make things easier (IMO). Finally, one
>> source
>> >> (one
>> >> > file) must be able to produce different format, like HTML, PDF,
>> ASCII,
>> >> > PS
>> >> or
>> >> > the like. And this whole thing must be scripted, so it's part of the
>> >> > development process (hopefully as a quality requirement).
>> >> >
>> >> > So... this raises the question: "which tool ?". Professional
>> >> documentation
>> >> > writer, if any here, may help. I'm not a doc write, but used LaTEX,
>> >> Docbook
>> >> > and ReST a litlle. Recently, I had a look at Asciidoc, and it seems
>> >> > quite
>> >> a
>> >> > nice choice (http://www.methods.co.nz/asciidoc/). It allows to have
>> a
>> >> > readable ASCII doc, and produce very nice HTML, XHTML, PDf, etc, ...
>> and
>> >> > intermediary format like Docbook. Highly configurable too.
>> >> >
>> >> > Ideally one would write his doc in his format, integrate it to the
>> main
>> >> book
>> >> > ("an introduction") but also upload it to our upcoming jalv2 website.
>> >> >
>> >> > I think I'll try to convert current Toon&Joep's document and let you
>> >> > have
>> >> a
>> >> > look at the results. In the meantime, if you have suggestions and/or
>> >> > objections... (and most importantly, will you agree to invest some
>> time
>> >> on
>> >> > this kind of tool ?)
>> >> >
>> >> > Cheers,
>> >> > Seb
>> >> > --
>> >> > Sébastien Lelonghttp://www.sirloon.nethttp://sirbot.org
>> >> >
>> >>
>> >
>> > >
>> >
>>
>> >>
>>
>
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en
-~----------~----~----~----~------~----~------~--~---
