eLua Development

[Elua-svn] r138 - trunk/docs

Classic

List

Threaded

6 messages Options

Frédéric THOMAS-5

[Elua-svn] r138 - trunk/docs

> New Revision: 138
>
> Added:
> trunk/docs/eLua_Manual.pdf
> Log:
> eLua doc migrating to PDF Format
> an eLua_Manual.pdf was added to docs
> separate .txt files will be removed soon

Not sure this is a good move.

I understand you want to generate a PDF out of a odt file. I am not
certain changes to the odt can easily tracked from svn, I mean, how
easy it is to see what are the changes between two revisions - and how
easy it is for contributors to make revisions to the file.

IMHO, something like HTML or Markdown or some other simple markup
could have provided for structure/pretty printing...

My two cents

Fred

Dado Sutter

[Elua-svn] r138 - trunk/docs

Hello Guys,
Thanks for the comments Fred ! We need to hear some more about it too.
SVN maintains correctly the ODT versions but you are right, it treats the
file as a binary and does not show diffs in text form.
The .ODT format was initially chosen to be close to the documentation
guys. I'm afraid HTML and Markup (and it's variations) are not options here,
if we don't offer a WYSIWYG editor but yes, we can try to come up with
something.
I actually think this is probably the major (and only :) problem with
Sputnik, to store content in HTML/Markdow rendering format, instead of XML
or a DB.

The advantages would be:
- to have SVN diff clearly reported on commits (as you've stated)
- to have the possibility to work on the Manual directly in our site, which
is a Wiki, with full HTML support. A tool could then grab the pages and
generate the Manual, ready to be converted to another format if needed (PDF
?)

But I don't see any easy solution now :(, as requiring HTML knowledge (or
even proximity :) from those we have today to help with the doc (writers,
translators, reviewers, ....) is not an option :(

Is there another format that could fullfill both the svn diff report
capability and decent/easy formatting needs ?
Is there a tool to make us use WYSIWYG in our Wiki and then automate the
Manual generation from it ?

I don't want to add complexity to this task, as we already have a
loooooooooong list of topics to work with :)
This is why the natural solution was to chose an Open Source widely used
Text Editor (Open Office) and an everybody-likes final format to read (PDF).

Tks for raising this debate !
Best
Dado

On Thu, Jan 1, 2009 at 11:25, Fr?d?ric Thomas
<berlios.de at thomascorner.com>wrote:

> > New Revision: 138
> >
> > Added:
> > trunk/docs/eLua_Manual.pdf
> > Log:
> > eLua doc migrating to PDF Format
> > an eLua_Manual.pdf was added to docs
> > separate .txt files will be removed soon
>
> Not sure this is a good move.
>
> I understand you want to generate a PDF out of a odt file. I am not
> certain changes to the odt can easily tracked from svn, I mean, how
> easy it is to see what are the changes between two revisions - and how
> easy it is for contributors to make revisions to the file.
>
> IMHO, something like HTML or Markdown or some other simple markup
> could have provided for structure/pretty printing...
>
> My two cents
>
> Fred
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20090101/b5490c73/attachment.html

BogdanM

[Elua-svn] r138 - trunk/docs

In reply to this post by Frédéric THOMAS-5

On Thu, Jan 1, 2009 at 3:25 PM, Fr?d?ric Thomas <berlios.de at thomascorner.com
> wrote:

You're very right, but do you have any idea of some HTML/markdown packages
that can fulfill our needs? Ideally we'd have something that:

- will show the docs on-line in the web page (although we're over Sputnik, I
think a simple HTML format should do just fine).
- will have the same docs packed in any official release
- will be able to also generate a PDF format for the docs (many people would
rather have all the documentation in one or a few more files than scattered
in a series of HTML documents).

Best,
Bogdan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20090101/b91274ce/attachment-0001.html

Dean Hall

[Elua-svn] r138 - trunk/docs

ReStructured Text (ReST) is a tool in the Python docutils package. It
has a readable text format and generates HTML and LaTeX (from which
the best-looking PDFs can be made). Since eLua build uses scons, I
didn't think another python tool would be too objectionable.

!!Dean

On Jan 1, 2009, at 09:24 , Bogdan Marinescu wrote:

> You're very right, but do you have any idea of some HTML/markdown
> packages that can fulfill our needs? Ideally we'd have something that:
>
> - will show the docs on-line in the web page (although we're over
> Sputnik, I think a simple HTML format should do just fine).
> - will have the same docs packed in any official release
> - will be able to also generate a PDF format for the docs (many
> people would rather have all the documentation in one or a few more
> files than scattered in a series of HTML documents).
>
> Best,
> Bogdan

Yuri Takhteyev

[Elua-svn] r138 - trunk/docs

In reply to this post by BogdanM

> You're very right, but do you have any idea of some HTML/markdown packages
> that can fulfill our needs? Ideally we'd have something that:

There is a tool called "pandoc" ("sudo apt-get install pandoc" on
Ubuntu) that converts markdown to latex, which can then be converted
to pdf with pdflatex. (See http://media.freewisdom.org/tmp/elua.pdf
for a sample output.) You can of course use your own latex template,
add title, etc.

If you want to use Sputnik for editing the documentation, It would be
easy to write a script that takes a list of nodes and concatenates
them into a single markdown file, which can then be fed to pandoc and
then to pdflatex.

Another possibility is POD, though it may be a little too restrictive.
Sergio Medeiros wrote a POD converter in Lua and we used to have a
Sputnik plugin for it, though it might be a little stale. (If there
existed a converter from restructuredtext to html written in Lua, it
would be very easy to make Sputnik use it. However, I don't believe
there is one.)

- yuri

--
http://sputnik.freewisdom.org/

BogdanM

[Elua-svn] r138 - trunk/docs

In reply to this post by Dean Hall

On Thu, Jan 1, 2009 at 6:26 PM, Dean Hall <dwhall256 at gmail.com> wrote:

> ReStructured Text (ReST) is a tool in the Python docutils package. It
> has a readable text format and generates HTML and LaTeX (from which
> the best-looking PDFs can be made). Since eLua build uses scons, I
> didn't think another python tool would be too objectionable.
>

Thanks, didn't know about that. Python tools are of course always welcomed
:)

Best,
Bogdan

>
>
> !!Dean
>
> On Jan 1, 2009, at 09:24 , Bogdan Marinescu wrote:
>
> > You're very right, but do you have any idea of some HTML/markdown
> > packages that can fulfill our needs? Ideally we'd have something that:
> >
> > - will show the docs on-line in the web page (although we're over
> > Sputnik, I think a simple HTML format should do just fine).
> > - will have the same docs packed in any official release
> > - will be able to also generate a PDF format for the docs (many
> > people would rather have all the documentation in one or a few more
> > files than scattered in a series of HTML documents).
> >
> > Best,
> > Bogdan
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20090102/909be972/attachment.html