[liblouis-liblouisxml] Re: liblouisutdml documentation
- From: "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
- To: liblouis-liblouisxml@xxxxxxxxxxxxx
- Date: Wed, 18 Jun 2014 08:33:24 -0500
A note on semantic actions. sem_names.h is a generated file. The basic
file is sem_enum.h . If you add a semantic action you must do it in
sem_enum.h and then run Makesemnames to generate sem_names.f .
Descriptive comments should be in sem_enum.h . It already contains
comments on various classes of semantic actions.Of course this is just
source code documentation.
John
On Wed, Jun 18, 2014 at 11:01:04AM +0100, Michael Whapples wrote:
> On the updating of the documentation from source code: Using
> something like doxygen would be an improvement as that would at
> least mean API documentation could be updated.
>
> As for user documentation, there might not be anything existing and
> we probably could not create anything totally generalised. However
> we could cover certain cases such as semantic actions (eg. having a
> script which parses sem_names.h and extracts the various semantic
> action names from that). May be to automatically fill in the
> description there could be comments or something which the script
> could use.
>
> I imagine something similar could be done to cover configuration
> options and the various options for styles.
>
> This would probably cover the main things which would be affected by
> source code changes, other changes probably would be more major and
> are probably less of an issue to require manual documentation
> updating.
>
> Michael Whapples
> On 18/06/2014 10:41, Christian Egli wrote:
> >On 06/18/2014 11:25 AM, Michael Whapples (Redacted sender
> >mwhapples@xxxxxxx for DMARC) wrote:
> >>Could you explain more as to what the macros for indexing and
> >>crossreferencing semantic actions is meant to do?
> >
> >If you look at the top of liblouisutdml.texi there are a bunch of
> >macros (look for @macro). For example there is a macro for
> >semantic actions and one for settings. These are then expanded
> >into the code up until the @end macro command. So if you type
> >@setting{inputTextEncoding, ascii8} for example it will create
> >
> >@tindex inputTextEncoding
> >@item inputTextEncoding ascii8
> >
> >i.e. the setting will have an item in the current table and it
> >will also have an entry in the Configuration Settings Index that
> >texinfo provides.
> >
> >For semantic actions the macro will create an item, an index entry
> >and an anchor so that you can easily reference to it with the
> >semanticref macro.
> >
> >>I removed the boxline semantic action, moving the functionality into a
> >>>style, but nothing has changed in the documentation. Is this macro
> >>>purely doing something internal in the documentation rather than the
> >>>more useful thing of synchronising with reality?
> >
> >Are you saying that changing the code should automatically change
> >the documentation? That would be a wonderful feature. If you show
> >me a system that can do this I'd be very happy.
> >
> >You will have to reflect code changes by updating the
> >documentation. There are systems (doxygen for example) that can
> >generate API documentation based on comments in the code. That is
> >something that I have been looking into. But user documentation
> >should be written specifically for that need and not extracted
> >from the code IMHO.
> >
> >Anyway hope this helps.
> >Christian
>
> For a description of the software, to download it and links to
> project pages go to http://www.abilitiessoft.com
--
John J. Boyer; President, Chief Software Developer
Abilitiessoft, Inc.
http://www.abilitiessoft.com
Madison, Wisconsin USA
Developing software for people with disabilities
For a description of the software, to download it and links to
project pages go to http://www.abilitiessoft.com
Other related posts:
