[GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 11, 2018, at 5:12 PM, David Cousens <davidcousens at bigpond.com> wrote:
> 
> Hi John,
> 
> I do understand that alternatives to docbook are being considered. 
> 
> I keep referring to it primarily because it is the current format, rather
> than necessarily the best or even what may be used in future. Perhaps with
> an assumption that whatever format is decided on, it will at least have the
> same conversion capabilities and the ability to construct an automated build
> workflow as are present in the current documentation tool chain. 
> 
> Also as a way of arguing for not embedding context sensitive help in hard
> code if it is avoidable. I do take the point though that such information
> does only change slowly if at all so I think a separate file perhaps with a
> more restricted editing access could be a way to handle that. 
> 
> The availability of some good open source free wsiwyg editors for markdown
> would certainly help  documenters with a less technical background and
> pandoc seems to be capable of building into a toolchain for converion for
> example. I haven't found out yet whether it uses some form of xls to control
> the conversion which is customizable.

David,

That misses the point a bit, which is that regardless of what format we keep the sources in the documents that users read will mostly be some form of HTML or PDF and we're limited to the feature set that those markup languages provide. For the current discussion that particularly applies with respect to cross-document links.

Regards,
John Ralls