Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
On 23-6-2018 16:44, Simonov Denis via Firebird-docs wrote: Mark Rotteveel wrote Thu, 14 Jun 2018 17:04:56 +0300: I tried to translate a small project from docbook to asciidoc. Conversion was successful, but some moments had to be finalized manually. Yes, some tweaks are needed. It might be possible that these are things that can be improved in the conversion tool itself. If you used https://github.com/asciidoctor/docbookrx then you may want to consider reporting issues there. Then I tried to generate html, it turned out well even with standard styles. I tried to generate a PDF it turned out to be acceptable, but I do not really like the default font. I think if you really want to translate the documentation to asciidoc, then the community needs to work out and set up a PDF generation style. That would certainly be the intent yes. The syntax highlight works well, but what to do with languages that are not represented as standard. How to set your own keywords for the syntax highlighting PSQL? That would be something to investigate. AsciiDoctor itself utilizes external syntax highlighting libraries (options are coderay, highlightjs, prettify, and pygments), and this would probably involve adding support for PSQL to (one of) those highlighters. Alternatively, one could just tag it with SQL and live with the deficiencies. And I would also like to know if there are IDEs for creating such documentation. I mean WYSIWYG, and not just highlight the syntax of asciidoc as in Nodepad++. On the other hand asciidoc itself is more readable than docbook. I'm not aware of any WYSIWYG editors for asciidoc, just editors with options for a (nearly) live preview. For example Visual Studio Code + AsciiDoc plugin by João Pinto, AsciidocFX, IntelliJ + AsciiDoc plugin, and probably others. -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
Mark Rotteveel wrote Thu, 14 Jun 2018 17:04:56 +0300: I tried to translate a small project from docbook to asciidoc. Conversion was successful, but some moments had to be finalized manually. Then I tried to generate html, it turned out well even with standard styles. I tried to generate a PDF it turned out to be acceptable, but I do not really like the default font. I think if you really want to translate the documentation to asciidoc, then the community needs to work out and set up a PDF generation style. The syntax highlight works well, but what to do with languages that are not represented as standard. How to set your own keywords for the syntax highlighting PSQL? And I would also like to know if there are IDEs for creating such documentation. I mean WYSIWYG, and not just highlight the syntax of asciidoc as in Nodepad++. On the other hand asciidoc itself is more readable than docbook. -- Simonov Denis -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
On 22-6-2018 11:41, Köditz, Martin wrote: Hi, is there a chance to get an online editor with asciidoc? Something like https://asciidoclive.com/edit/scratch/1. I think that would be very helpful as some people have trouble setting up a suitable environment. You can always work with an online editor. And if it is only for a few lines. That helps the entire project. Let's try to walk before we can run. I don't entirely see the necessity of this. Setting up editors is a lot easier compared to for example Docbook, but if you want you can always contribute a setup :). Alternatively, you could always test if using the GitHub editor is sufficient: it doesn't support side-by-side preview, but it does render a preview of the asciidoc file on a separate tab. Mark -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
Issue 921 opened on github. (Asciidoctor-pdf) Cheers, Norm. -- Sent from my Android device with K-9 Mail. Please excuse my brevity and any "auto corrections" that are just wrong!-- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
Hi, is there a chance to get an online editor with asciidoc? Something like https://asciidoclive.com/edit/scratch/1. I think that would be very helpful as some people have trouble setting up a suitable environment. You can always work with an online editor. And if it is only for a few lines. That helps the entire project. Regards, Martin -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
On 2018-06-21 21:04, Norman Dunbar wrote: On the grounds of experimenting, I've been able to install asciidoctor and asciidoctor-pdf at work and I'm quite impressed now at how well it has come on since I last looked at it. I would like to be able to convert to EPUBs as well as HTML and PDF, but it's proving a tad difficult to get the asciidoctor-epub3 to install. There are dependency hell problems (on Windows as well as Linux). I have only used asciidoctor from gradle (which takes care of the dependencies, and does not need to install anything). I will see if that also supports epub. I'm extremely impressed at how (relatively) easy is seems to be to amend a PDF theme, I've made one for work based on the default but with a few small changes to add a logo to the title page, headers and footers etc, and a minor adjustment to the base font size and line size to match. Very nice - at least my boss was impressed! I did have to change the justification to left though as I was getting those badly justified lines too often for comfort. If you have a good and simple example for reproduction, it might be worth reporting on https://github.com/asciidoctor/asciidoctor-pdf Mark -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
On 16-6-2018 15:42, Paul Vinkenoog wrote: I was wondering how people think about migrating from docbook to asciidoc. Asciidoc is an "almost plain text" format that is used a lot these days for documentation (as an example, Hibernate and Spring switched from docbook to asciidoc), as its markup is a lot simpler and allows for editing with basic tools and is even - relatively - readable without having rendered it to HTML or PDF. It has been based on docbook (as originally asciidoc was converted to docbook before actually rendering). Pros of asciidoc: - Simpler, could lower bar of entry for contributions I'm skeptical about that. People can write in plaintext if they want and let the doc team take care of the rest. I can't remember if this has brought us even one contribution. Maybe. I didn't even know that (but then again, I didn't actively search for that). Is that mentioned on the site somewhere? That said, I have nothing against a simpler syntax. - More readable Absolutely. - Wider support in tools Than what? DocBook? And in how much would this benefit us? I mean, you only need one good set of tools that render the docs the way you like them. I actually mean support in (free) editors, eg there is AsciidocFX, plugins for IDEs and editors, including preview support (Please notice that these questions are not meant rhetorically; I really want to know. Anything that makes our life simpler while still producing quality output I'd welcome!) Cons: - Some of the more semantic features of docbook are not supported by asciidoc (but we don't really use those AFAIK). One thing I wonder is if AsciiDoc supports automatic index building, as DocBook and our tool chain do. This is extremely helpful. See e.g. our Quick Start Guides and the Firebird Null Guide. You can mark index terms in the document just like in docbook, see https://asciidoctor.org/docs/user-manual/#user-index and for the PDF this can build an index for you (if you declare an index section), this hasn't been done for html output (yet). Then again, I hardly ever use an index in non-print. I usually just search (which is harder with multi-page docs like Firebird's HTML docs though). There are also tools like Antora, but that is for building integrated documentation sites, including an online search (eg see https://docs.antora.org/antora/1.0/). Antora uses asciidoc, but requires a specific structure/organization of files to be able to generate the documentation site as linked). Could be interesting for the Firebird project, but I'm not sure if that is worth doing. - Tools for asciidoc are simpler (compared to - for example - XMLMind; might be a pro) Yes, although the good thing about XMLMind is that it doesn't allow you to produce invalid XML, whereas if you screw up your AsciiDoc I don't know what the effect on the output will be and if you'll notice your error in a very big document. With the preview support in most editors that is actually less of a problem, and in my experience (both with the Jaybird manual and at work), render errors due to markup problems are usually pretty localized (unless you forgot to close a table). The two HTML renderings can be found on https://mrotteveel.github.io/firebird-documentation/ Overall, it looks good; certainly not worse than our current HTML. There are some things I don't like, but that's a matter of editing the stylesheets. I don't like the PDF. It looks too much like HTML copied into a book. (I don't know if this is a good argument - probably not - but it just doesn't "look right" to me. A well-rendered PDF can and should be much more pleasant to read.) Compared to the existing Firebird PDFs, I think the biggest difference is a slightly smaller margin, a different font, no page header with the current section title, and no page break on a new section. That is - I think - a matter of tweaking the theme, and otherwise there is always the option - at build time - to transform asciidoc to docbook (version 5 or 4.5) and use another rendering pipeline (asciidoc can be considered a subset of docbook, except not XML). In any case, think it over. For now I'll try and rewrite the existing ant build to gradle. Mark -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
16.06.2018 10:14, Mark Rotteveel wrote: Seconded, the output looks very good. I would support switching to this toolset if it can handle our requirements. I think the output should not be a deciding factor. If that is the thing that counts, then overhauling the existing docbook stylesheets and transformations could be enough :) But it looks like a nice bonus -- no need to redesign our stylesheets ;-) I'm thinking more in terms of making it easier to write docs, and hopefully getting more contributions (big and small) by lowering the bar (docbook XML can be rather daunting). Sure. And I agree here too (as the one who tried that in the past). Dmitry -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
On 16-6-2018 09:01, Dmitry Yemanov wrote: 15.06.2018 12:26, Alexey Kovyazin wrote: I like the result - html docs looks really cool. Also, I think it is more suitable for the translation. Seconded, the output looks very good. I would support switching to this toolset if it can handle our requirements. I think the output should not be a deciding factor. If that is the thing that counts, then overhauling the existing docbook stylesheets and transformations could be enough :) I'm thinking more in terms of making it easier to write docs, and hopefully getting more contributions (big and small) by lowering the bar (docbook XML can be rather daunting). Mark -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
15.06.2018 12:26, Alexey Kovyazin wrote: I like the result - html docs looks really cool. Also, I think it is more suitable for the translation. Seconded, the output looks very good. I would support switching to this toolset if it can handle our requirements. Dmitry -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
On 16-6-2018 00:05, Norman Dunbar wrote: Yes indeed, it does look smart. Unfortunately, the pdf of isql suffers from formatting errors, in justification, Appendix A - second line, first paragraph for example. I have used the default asciidoctor-pdf theme for generating the PDF, and that theme applies align: justify for paragraphs. You just notice it specifically for this paragraph, because of the long URL. I trie asciidoc and asciidoctor some time back, but I didn't get on with it/them. > I used Sphinx-doc for a project a while back, that was much better, but requires Python etc. With github and sphinx you can get an automatic build on commit/push and the pdf, html and epub (I think) can be uploaded automagically to readthedocs.io. For the jaybird-manual I have setup an automatic build and publish to GitHub Pages yesterday (see my other mail for links). I use ReStructuredText at work to create version controllable sources for pdf and Word (hack, spit) documents. Currently I convert with Pandoc - which I suspect will read docbook and write asciidoc, if necessary - although it's better to convert to LaTeX, do some editing and then generate the pdf. That gives a much better output. I'm rather fond of these plain text sources that can generate almost anything! Yes, me too. -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
As a more complete example, you can also take a look at the jaybird-manual at https://github.com/FirebirdSQL/jaybird-manual Its build automatically published to https://firebirdsql.github.io/jaybird-manual/jaybird_manual.html Mark On 14-6-2018 16:04, Mark Rotteveel wrote: I'm trying to modernize the build of the documentation by converting it to gradle (which should allow us to do away with manual setup and downloading of things, and may fix issues with more recent Java versions), but I got side-tracked into experimenting with asciidoc / asciidoctor (see https://asciidoctor.org/). I was wondering how people think about migrating from docbook to asciidoc. Asciidoc is an "almost plain text" format that is used a lot these days for documentation (as an example, Hibernate and Spring switched from docbook to asciidoc), as its markup is a lot simpler and allows for editing with basic tools and is even - relatively - readable without having rendered it to HTML or PDF. It has been based on docbook (as originally asciidoc was converted to docbook before actually rendering). Pros of asciidoc: - Simpler, could lower bar of entry for contributions - More readable - Wider support in tools Cons: - Some of the more semantic features of docbook are not supported by asciidoc (but we don't really use those AFAIK). - Tools for asciidoc are simpler (compared to - for example - XMLMind; might be a pro) Conversion could be done document by document (Spring did that), that will probably complicate the setup, but would allow for spreading out the conversion. I have converted two documents from docbook to asciidoc using https://github.com/asciidoctor/docbookrx, and fixed a number of obvious issues with features not supported by the converter. I haven't checked the documents fully, so it is possible some other things 'disappeared' or render incorrectly in this conversion. I have also enabled table of content rendering, otherwise all the defaults have been used (including default styles). The two HTML renderings can be found on https://mrotteveel.github.io/firebird-documentation/ Sources are on https://github.com/mrotteveel/firebird-documentation/tree/asciidoc-conversion-experiment Specifically (linking to raw, because otherwise GitHub renders asciidoc files): https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/fbutil_isql.adoc and https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/wireprotocol.adoc (switch extension to .xml to view the docbook sources) Example of how GitHub renders it from the repository: https://github.com/mrotteveel/firebird-documentation/blob/asciidoc-conversion-experiment/src/docs/firebirddocs/fbutil_isql.adoc -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor
Mark, Thats very smart I like it. Regards Paul > -Original Message- > From: Mark Rotteveel [mailto:m...@lawinegevaar.nl] > Sent: 14 June 2018 16:05 > To: Chatter regarding Firebird documentation > Subject: [Firebird-docs] Experimenting with asciidoc / asciidoctor > > > I'm trying to modernize the build of the documentation by converting it > to gradle (which should allow us to do away with manual setup and > downloading of things, and may fix issues with more recent Java > versions), but I got side-tracked into experimenting with asciidoc / > asciidoctor (see https://asciidoctor.org/). > > I was wondering how people think about migrating from docbook to > asciidoc. Asciidoc is an "almost plain text" format that is used a lot > these days for documentation (as an example, Hibernate and Spring > switched from docbook to asciidoc), as its markup is a lot simpler and > allows for editing with basic tools and is even - relatively - readable > without having rendered it to HTML or PDF. It has been based on docbook > (as originally asciidoc was converted to docbook before actually rendering). > > Pros of asciidoc: > - Simpler, could lower bar of entry for contributions > - More readable > - Wider support in tools > > Cons: > - Some of the more semantic features of docbook are not supported by > asciidoc (but we don't really use those AFAIK). > - Tools for asciidoc are simpler (compared to - for example - XMLMind; > might be a pro) > > Conversion could be done document by document (Spring did that), that > will probably complicate the setup, but would allow for spreading out > the conversion. > > I have converted two documents from docbook to asciidoc using > https://github.com/asciidoctor/docbookrx, and fixed a number of obvious > issues with features not supported by the converter. I haven't checked > the documents fully, so it is possible some other things 'disappeared' > or render incorrectly in this conversion. I have also enabled table of > content rendering, otherwise all the defaults have been used (including > default styles). > > The two HTML renderings can be found on > https://mrotteveel.github.io/firebird-documentation/ > > Sources are on > https://github.com/mrotteveel/firebird-documentation/tree/asciidoc-conversion-experiment > > Specifically (linking to raw, because otherwise GitHub renders asciidoc > files): > > https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/f butil_isql.adoc and https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/wireprotoco l.adoc (switch extension to .xml to view the docbook sources) Example of how GitHub renders it from the repository: https://github.com/mrotteveel/firebird-documentation/blob/asciidoc-conversion-experiment/src/docs/firebirddocs/fbutil_isql.adoc -- Mark Rotteveel -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs -- Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
