Hi, I'm wondering if a good way to think about asciidoc is as an alternative markup langauge that can produce html5 and docbook.
It seems to have another set of markup language. In this sense, it could be an alternative front end for DocBook, which it uses to get to PDFs, I think. Does that sound right? -Marshall On 8/16/2017 4:51 PM, Marshall Schor wrote: > 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 >
