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 ascii8i.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 astyle, 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
