Hi, Asciidoc looks pretty nice.
When I looked at the github link to the master source, the browser displayed it in html format form. There was a button to look at it in "raw text". Does github automatically "render" these? Do you do your authoring in the rawtext format? Cheers. -Marshall On 8/16/2017 3:49 PM, Richard Eckart de Castilho wrote: > Hi, > > for drafting and discussing stuff, Google Docs is a great thing. > > But actual documentation, should IMHO be in a diff-friendly format > in the repository. I've grown quite fond of asciidoctor which can > generate nice HTML and PDF documents without the horrendous overhead > and complexity of Docbook XML. Also, these days Eclipse by default comes > with a basic "preview" support for Asciidoc. > > These here are generated using Asciidoctor: > > - https://webanno.github.io/webanno/releases/3.2.2/docs/user-guide.html > - https://webanno.github.io/webanno/releases/3.2.2/docs/user-guide.pdf > > The sources for these documents are here: > https://github.com/webanno/webanno/tree/master/webanno-doc > > The DKPro Core documentation is also done using Asciidoc. However, here > most of the documentation is actually autogenerated by aggregating information > from different sources (UIMA descriptors, JavaDoc, etc.) and generating > asciidoc source files from them which are then finally rendered into HTML. > > https://dkpro.github.io/dkpro-core/releases/1.8.0/docs/component-reference.html > > The dynamic TOC on the side is done using tocify. > > Cheers, > > -- Richard > >> On 16.08.2017, at 15:34, Marshall Schor <[email protected]> wrote: >> >> Hi, >> >> I want/need to create a nice doc, with diagrams, etc., together with other >> interested parties in our community. >> >> The particular doc driving this is one related to UIMA-5536, and is around >> the >> subtleties and design-for-least-surprise notions, involved with iterators and >> indexes without type priorities. >> >> I thought it would be nice to be able to collaboratively edit such a doc, >> rather >> than just having long email chains. It seems google docs might fit the >> needs, well. >> >> At some point, I suppose we could consider using google docs for actual >> documentation work, too. There are ways to export and import (for example to >> microsoft word), where we could have some kind of official "source" in svn. >> There are ways to create PDFs, and web-page formats, too. And there is an >> extensive permissions system. >> >> WDYT? >> >> -Marshall >
