On Mon, Dec 20, 2010 at 2:16 PM, Thomas Gstädtner <tho...@gstaedtner.net> wrote:
> On Fri, Dec 17, 2010 at 22:13, Lionel Orry <lionel.o...@gmail.com> wrote:
>> Kim Lester <kim <at> dfusion.com.au> writes:
>>
>>>
>>> All,
>>>
>>> A few notes and two requests (marked *** )
>>>
>>> [...]
>>> Incidentally I wrote this in OO simply because writing either doxygen or xml
>>> is not a good way to evolve a
>>> large complex document. I've written large docs in TeX with vi before and
>>> whilst it is good for producing
>>> consistent output it sucks from the point of view of massive cut/pastes and
>>> "creative flow". Eventually
>>> this doc _could_ be converted to xml or tex or something but not just now.
>>>
>>
>> Hi Kim,
>>
>> I've been using TeX for a long time so don't get me wrong, but there exist
>> now
>> new formats that encourage the creative flow, as you say, by abstracting the
>> formatting stuff, and that provide the source as a text file (devs love text
>> files... They really do. They hate binary stuff apart from edje and eet files
>> of course.), so the manual could also be versioned on the official svn repo.
>> It could even be provided as README-like files.
>>
>> Such formats include AsciiDoc, RestructuredText, Textile, Markdown, etc.
>>
>> I am personally using AsciiDoc for, well... nearly everything I write when
>> it's a bit technical. If you think it's a good idea to see what it looks
>> like,
>> give me a hour or two to convert your doc tomorrow and I'll show you the
>> result.
>>
>> I'm not the right person to talk about the content though, but I appreciate
>> the effort very much. Good doc makes enjoyable software.
>>
>> -Lionel
>
> I fully agree.
> I highly suggest to look into Markdown. While having a few flaws in
> layouting hat other systems might not share, it still has a ton of
> possibilities to format text while being extremely simple and
> especially plaintext-friendly.
> Markdown format just looks like plain textfile format, just like any
> readme-file and so on uses anyway, so vi or emacs is just fine, and
> yet you can produce appealing online documentations with CSS.
>
Hi Thomas,
this is pretty much the same with AsciiDoc, the text file format is
very plain. I suggested it because I use it a lot. I did not want to
spam the list but since you react about that (and it's a very good
point, we should react and get the best solution), I attach an archive
with a first draft of the manual converted to AsciiDoc format. See for
yourself. It's missing a few formatting bits and embedded URLs
(lacking free time, sorry) but it should show you the point.
As an additional note, tools provided with or for asciidoc allow
conversion of the original text file to html, xhtml, docbook-xml,
LaTeX (though not maintained much), pdf via docbook and fop or dblatex
backend, man pages (see git man pages), Slidy presentation system, and
includes automatic syntax highlighting for all languages supported by
pygments or GNU source-highlight, automatic diagram generation with
ditaa or graphviz, and other goodies. Just to say that the feature
list is, IMHO, wider than Markdown which is a very good specification
but is mostly related to wiki formatting and thus HTML generation.
Correct me if I'm wrong.
I think we can count on feedback from Kim and others when the holidays
period is finished.
Regards,
Lionel
------------------------------------------------------------------------------
Lotusphere 2011
Register now for Lotusphere 2011 and learn how
to connect the dots, take your collaborative environment
to the next level, and enter the era of Social Business.
http://p.sf.net/sfu/lotusphere-d2d
_______________________________________________
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
