I dispute that the format question is a waste of time. If those with the knowledge for the content do not have the skills to deal with the format one needs to edit the documentation, then those people are unable to update the documentation directly.
To rely on others to insert submitted documentation content is also not working. John said he has sent detail of the macro feature a number of times to the list (when I do not know) but this information has never got in the actual documentation.
May be the description John sent was not up to documentation standards, but was there ever feedback on what was needed to bring it to such a standard. Also where is there any information for those writing content so they can ensure it meets a suitable standard, without that we will end up with many submissions of an unsuitable quality and thus more work for everyone as it will need comments for correction and the person to go away and correct previous work. I am unwilling to engage in a process where it is likely I will have to guess what is wanted and more than likely go away and correct it (after all a guess is only that so there is a good chance of not getting it right).
Michael Whapples On 18/06/2014 08:43, Christian Egli wrote:
Hi allOn 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 Pythonbackground, 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.comFor 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
