Sorry, forgot to reply to all.
L.
Début du message réexpédié :
De : Louis Ricard louis.ricard@polytechnique.edu
Date : 15 juin 2009 20:23:50 HAEC
À : Marcus D. Hanwell marcus@cryos.org
Objet : Rép : [Avogadro-devel] Help with documentation, screen casts
and tutorials
Hi Marcus.
Nice to see you back and congratulations to the mother and
you!
Personnally, even if docbook is great, thinking that a majority
of users would be from the Windows community, I think that
PDF would be preferable and more universal.
Would it be possible to post this in Launchpad for translations?
Louis
Le 15 juin 09 à 19:41, Marcus D. Hanwell a écrit :
Now that our UI and strings are frozen this is a great time to
improve
our documentation. We think the best approach is to draft out the
documentation on our wiki, and then push this into docbook format for
distribution with Avogadro. We would like to appeal to all of our
developers, and interested users to help us flesh out the
documentation
on the wiki.
Personnally, even if docbook is great, thinking that a majority
of users would be from the Windows community, I think that
PDF would be preferable and more universal.
I think the idea is that Docbook can generate PDF files which would
actually “ship” with the binaries.
I don’t know a good approach for translating. Launchpad is set up for
short strings, so I don’t know how it would handle a full manual –
maybe there’s another tool like Launchpad out there for manuals?
-Geoff
On Mon, Jun 15, 2009 at 11:51 AM, Geoffrey
Hutchisongeoff.hutchison@gmail.com wrote:
Personnally, even if docbook is great, thinking that a majority
of users would be from the Windows community, I think that
PDF would be preferable and more universal.
I think the idea is that Docbook can generate PDF files which would
actually “ship” with the binaries.
I don’t know a good approach for translating. Launchpad is set up for
short strings, so I don’t know how it would handle a full manual –
maybe there’s another tool like Launchpad out there for manuals?
The Ubuntu Doc team uses docbook + xml2po to get things translated on
Launchpad. A fairly simple script can be used to make the .pot and
convert the translated .po files back into docbook.
-Jordan
Personnally, even if docbook is great, thinking that a
majority
of users would be from the Windows community, I think that
PDF would be preferable and more universal.
I think the idea is that Docbook can generate PDF files which
would
actually “ship” with the binaries.
Does Docbook generate PDFs with clickable cross references so
that a command can be described once in the appropriate section
and then related commands or instructions just have a link to
it?
The handiest documentations for simulation codes that I have
seen include a lot of cross references as a nod to how people
use the documentation rather than limiting themselves to a
linear book with an index. What I have liked as a user is a
set of heavily cross referenced html files shipped with the
code rather than a flat pdf.
Joanne Budzien wrote:
Personnally, even if docbook is great, thinking that a
majority
of users would be from the Windows community, I think that
PDF would be preferable and more universal.
I think the idea is that Docbook can generate PDF files which
would
actually “ship” with the binaries.
Does Docbook generate PDFs with clickable cross references so
that a command can be described once in the appropriate section
and then related commands or instructions just have a link to
it?
The handiest documentations for simulation codes that I have
seen include a lot of cross references as a nod to how people
use the documentation rather than limiting themselves to a
linear book with an index. What I have liked as a user is a
set of heavily cross referenced html files shipped with the
code rather than a flat pdf.
I will have to check on the cross referencing, but I think that this is
possible. Docbook is a lot like LaTeX and can target multiple formats
such as HTML and PDF. I would like to distribute a PDF and HTML version
of the documentation with Avogadro. It sounds like these can be put onto
Launchpad for translation too.
Does this sound reasonable? I am much more familiar with LaTeX
personally, but I think that Docbook has everything we need. I still
think that the wiki would likely be the best place to draft out these
ideas, get screenshots up etc. Once they are in reasonable shape it is
relatively easy to move the docs across to the Docbook format.
It would be great to compile a list of all the people who author
content, add an authors list and get the manual localized once we have a
complete draft. Launchpad has certainly been a great tool to get
Avogadro translated, so it seems like we should stick with it if we can
for our manual.
Thanks,
Marcus
On Jun 15, 2009, at 3:08 PM, Joanne Budzien wrote:
What I have liked as a user is a set of heavily cross referenced
html files shipped with the
code rather than a flat pdf.
Of course PDF can also have hyperlinks. But Dockbook supports export
to HTML as well as PDF.
http://bochs.sourceforge.net/doc/docbook/documentation/basics.html
Jordan, glad to know about the Launchpad-migration of manuals. We
could obviously add that as a new translation template, which is
great. The downside is that any screenshot with text will require
translated screenshots too!
-Geoff