[liblouis-liblouisxml] Re: liblouisutdml documentation
- From: Christian Egli <christian.egli@xxxxxx>
- To: liblouis-liblouisxml@xxxxxxxxxxxxx
- Date: Wed, 18 Jun 2014 09:43:33 +0200
Hi all
On 06/17/2014 11:13 PM, Michael Whapples (Redacted sender
mwhapples@xxxxxxx for DMARC) wrote:
I agree something else would be better. ePub might be acceptable to me
although I might prefer something like ReStructureText (RST) or another
of the plain text markup languages which could be converted to many
outputs.
The problem is not the format (texinfo _is_ a plain text markup language
which _can_ be converted to many outputs). The problem is that nobody
writes the documentation. Let me put some historical perspective into
this discussion: Before I converted the documentation to texinfo (and
integrated it in the build process) there were actually two documents.
One was html and the other one was a plain text file. You never knew if
they were in sync. Sometimes John would update one and not the other. So
having one source to produce html and a plain text file from it is
already a big improvement. I then went through all of the opcodes and
semantic actions, created some macros to help with the documentation, so
we get a nice index and cross referencing. There is more to the texinfo
documentation than meets the unsuspecting eye.
I think it would be more important to work on the contents of the
documentation. The macro feature might have been described in a mail
once. But as far as I'm concerned. If a feature is not documented it
doesn't exist.
The whole format discussion is a classic bike shedding argument aka a
waste of time. The documentation itself is important not the format.
As for epub, yes, you can convert texinfo to docbook and then use a
number of tools (pandoc, dbtoepub) to convert it to epub.
Thanks
Christian
However my preference might be influenced by my Python
background, at least still with XML there are plenty of editors which
can simplify the task should one want to work that way.
Michael Whapples
On 17/06/2014 20:24, John J. Boyer wrote:
I have never been keen on texinfo, but some people on this list really
like it. I would rather see the documentation in an xml flavor, such as
epub.
One thing people could do is submit documentation for particular
features as text files in attachments to messages to this list.
John
On Tue, Jun 17, 2014 at 06:15:45PM +0100, Michael Whapples wrote:
As John has commented, it appears that nobody is updating the
documentation in liblouisutdml.
There are whole features undocumented (eg. the macros feature,
assigning a style without a semantic action, etc). Also there are
probably things which need better explanations.
So we need to ask the question why is the documentation not being
updated and what can be done to improve the situation?
Speaking for myself, the use of texinfo is a roadblock for me to
update it, and also at the moment there are too many unknowns in the
workings of liblouisutdml for me sometimes to clarify things which
are not clear in the documentation (looking at the source code
sometimes does not even help, it possibly confuses it even more and
one cannot be sure whether the actual working of the code is the
intended behaviour when the code is the only reference).
What is the case for others involved in liblouisutdml (either simply
using it or may be developing it) as to why they do not update the
documentation?
Do we have a simple lack of people?
Michael Whapples
For a description of the software, to download it and links to
project pages go to http://www.abilitiessoft.com
For a description of the software, to download it and links to
project pages go to http://www.abilitiessoft.com
--
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland
-----
Tag der offenen Tuer:
Die SBS laedt Sie herzlich ein: 28. Juni 2014 von 9 bis 16 Uhr.
Mehr Informationen erhalten Sie unter http://www.sbs.ch/offenetuer
For a description of the software, to download it and links to
project pages go to http://www.abilitiessoft.com
Other related posts:
