firebird-docs — chat stuff about documentation

Re: [Firebird-docs] German translation of ODBC/JDBC Driver manual

[Paul V. <pa...@vi...>]

Hi Martin,

>  no, there is no particular reason. Who Who should get the html version?

We usually build HTML and PDF and place them on the website. But I forgot you don't have CMS access (or do you?)

Anyway, you can send me the zipped HTML version but I can also build it myself and place it on the server.

Cheers,
Paul

Re: [Firebird-docs] German translation of ODBC/JDBC Driver manual

[Köditz, M. <Mar...@it...>]

Hi Paul,

no, there is no particular reason. Who Who should get the html version?

Regards,
Martin

Re: [Firebird-docs] German translation of ODBC/JDBC Driver manual

[Paul V. <pa...@vi...>]

Hi Martin, apologies for the delayed reply.

> I've just finished the German translation of ODBC/JDBC Driver manual. I pushed the source code on Github.

Thanks, that must have been a lot of work!

I was wondering though: is there a particular reason why you only produced a PDF and no HTML version?

Cheers,
Paul Vinkenoog

[Firebird-docs] German translation of ODBC/JDBC Driver manual

[Köditz, M. <Mar...@it...>]

Hi,

I've just finished the German translation of ODBC/JDBC Driver manual. I pushed the source code on Github.

Regards
Martin

Re: [Firebird-docs] How to build ODBC doc?

[Köditz, M. <Mar...@it...>]

Hi Paul,

it is working. Thank you.

Regards
Martin

Re: [Firebird-docs] How to build ODBC doc?

[Paul V. <pa...@vi...>]

Hi Martin,

> which command do I have to use to create the ODBC documentation?

This ought to do it, I guess:

  build <target> -Dbase=refdocs -Did=fbodbc205

<target> being html, pdf, docs, monohtml, etc.

Cheers,
Paul

[Firebird-docs] How to build ODBC doc?

[Köditz, M. <Mar...@it...>]

Hi,

which command do I have to use to create the ODBC documentation?

Regards,
Martin

Re: [Firebird-docs] Questions about documentation build

[Mark R. <ma...@la...>]

On 8-7-2018 15:28, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
>> 1. Is the monohtml task ever actually used? If so for which documents?
> 
> Helen used it for the Release Notes and some other documents. But she
> seems to have switched completely to chunked HTML now.
> 
> Monohtml might still be useful for small howtos, fact sheets etc.
> Would it mean a lot of extra work to keep it?

No, I saw some oddities in how it worked, and if it wasn't used, it 
wouldn't make sense to sort that out.

>> 2. In src/docs/xsl/ some of the stylesheets (eg fo.xsl, html.xsl and
>> htmlbase.xsl) have relative paths to the stylesheets in
>> docbook-stylesheets. If I want to be able to automatically get the
>> necessary stylesheets, I need to be able to use the catalog definition,
>> eg instead of
>>
>> <xsl:import
>> href="../../../tools/docbook-stylesheets/html/chunk-common.xsl"/>
>>
>> it would use
>>
>> <xsl:import
>> href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-common.xsl"/>
>>
>> And then the catalog file from the stylesheet dependency would resolve
>> that to the correct files. Is there any other reason for the use of
>> these relative paths other than the build itself?
> 
> Our stylesheet customisations are based on a specific version of the
> DocBook stylesheets (currently 1.72.0 - eleven years old but works for us).
> By keeping those in a local copy we ensure that everything keeps working
> - and looking - as expected no matter what happens on the DocBook side.

I'll see if there exists a dependency with that version, otherwise I may 
just depend on the existing zip file from the Firebird site. Or we may 
need to spend time to update (and I'm not sure if that is worth it).

> It also means we can build our targets even when docbook.sourceforge.net
> is down or slow, or if our own Internet connection is down.

No, that is not how it would work in the new setup. I add a dependency 
on zip files with the XSL and DTD files, and define a catalog manager 
which will make the XSLT engine use the XSL files from the jar file: the 
URL is just used as a unique identifier, not the actual resource 
location (URI vs URL).

> Previous updates of the DocBook stylesheets have been known to break
> some of our customisations or cause unwanted layout effects. That's OK
> as long as these updates (and whether we apply them or not) are under
> our control. But if we just link to the current online version these
> things will surprise us (and we may not even notice them immediately
> if we build a big document).

I'll try to find a way to approach this. Personally, I think the 
Firebird documentation style could use with some freshing up. On the 
other hand, spending time to do that, would be an investment that might 
lead away from migrating to asciidoc in the long term.

> Of course we can link to a specific version (after testing it and
> possibly having to adapt some of our own templates). This prevents
> unpleasant surprises, but we still depend on an Internet link (OK,
> or browser cache) to build the docs. Personally I always try to
> avoid such dependencies as much as possible.

The internet link is only necessary when the zipfile(s) with xsl and/or 
dtd is not yet in the local gradle cache. Afterwards, bar certain cache 
refreshes/clean ups, it will always refer to the local cache. The 
advantage on the other hand is that it reduces the manual steps 
necessary to get the documentation build to work, which will make it 
easier. It will also allow for creating an automated build that can be 
executed on each commit and that would work the same as a local build.

>> 3. Similarly, the xml sources define relative paths to the DTD:
>>
>> <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
>> "../../tools/docbook-dtd/docbookx.dtd">
>>
>> If I'm going to do away with the tools folder, these become invalid.
>> Is that a problem?
> 
> Well, it would break the build, for one thing ;-)

Not if the catalog manager is correctly configured :)

> But we could link to the online version (again introducing a dependency
> on an Internet link and the availability of an online resource).

It would be a dependency on a zip-file that is downloaded automatically 
but kept in cache.

>> Otherwise I can always add a task that automatically downloads and
>> unzips this to that location.
> 
> If it's not too much work, I would like that. That way we would have our
> local cache.
> 
> I guess the same could be done with the DocBook stylesheets - if it's
> not too much work.

My suggestion to automatically unzip was more for when something outside 
the build needed the files; the build wouldn't be needing it as it would 
use a zip-file on its classpath.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Questions about documentation build

[Paul V. <pa...@vi...>]

Mark Rotteveel wrote:

> As I mentioned before, I'm reworking the build to gradle so that
>
> 1. We can do away with the old ant version that is not compatible with 
> recent Java versions
> 2. Automatically get the necessary libraries and other dependencies (so 
> no more manually getting the lib folder (and hopefully: tools)) to build
>
> However, I'm running into a number of things that I'd like some input on.
>
> 1. Is the monohtml task ever actually used? If so for which documents?

Helen used it for the Release Notes and some other documents. But she
seems to have switched completely to chunked HTML now.

Monohtml might still be useful for small howtos, fact sheets etc.
Would it mean a lot of extra work to keep it?

> 2. In src/docs/xsl/ some of the stylesheets (eg fo.xsl, html.xsl and 
> htmlbase.xsl) have relative paths to the stylesheets in 
> docbook-stylesheets. If I want to be able to automatically get the 
> necessary stylesheets, I need to be able to use the catalog definition, 
> eg instead of
>
> <xsl:import 
> href="../../../tools/docbook-stylesheets/html/chunk-common.xsl"/>
>
> it would use
>
> <xsl:import 
> href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-common.xsl"/>
>
> And then the catalog file from the stylesheet dependency would resolve 
> that to the correct files. Is there any other reason for the use of 
> these relative paths other than the build itself?

Our stylesheet customisations are based on a specific version of the
DocBook stylesheets (currently 1.72.0 - eleven years old but works for us).
By keeping those in a local copy we ensure that everything keeps working
- and looking - as expected no matter what happens on the DocBook side.

It also means we can build our targets even when docbook.sourceforge.net
is down or slow, or if our own Internet connection is down.

Previous updates of the DocBook stylesheets have been known to break
some of our customisations or cause unwanted layout effects. That's OK
as long as these updates (and whether we apply them or not) are under
our control. But if we just link to the current online version these
things will surprise us (and we may not even notice them immediately
if we build a big document).

Of course we can link to a specific version (after testing it and
possibly having to adapt some of our own templates). This prevents
unpleasant surprises, but we still depend on an Internet link (OK,
or browser cache) to build the docs. Personally I always try to
avoid such dependencies as much as possible.

> 3. Similarly, the xml sources define relative paths to the DTD:
>
> <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
> "../../tools/docbook-dtd/docbookx.dtd">
>
> If I'm going to do away with the tools folder, these become invalid.
> Is that a problem?

Well, it would break the build, for one thing ;-)

But we could link to the online version (again introducing a dependency
on an Internet link and the availability of an online resource).

> Otherwise I can always add a task that automatically downloads and
> unzips this to that location.

If it's not too much work, I would like that. That way we would have our
local cache.

I guess the same could be done with the DocBook stylesheets - if it's
not too much work.

Cheers,
Paul

[Firebird-docs] Questions about documentation build

[Mark R. <ma...@la...>]

I think Paul is probably the one who knows the most about this, but I'll 
post to the list to be sure I don't miss anything.

As I mentioned before, I'm reworking the build to gradle so that

1. We can do away with the old ant version that is not compatible with 
recent Java versions
2. Automatically get the necessary libraries and other dependencies (so 
no more manually getting the lib folder (and hopefully: tools)) to build

However, I'm running into a number of things that I'd like some input on.

1. Is the monohtml task ever actually used? If so for which documents?

2. In src/docs/xsl/ some of the stylesheets (eg fo.xsl, html.xsl and 
htmlbase.xsl) have relative paths to the stylesheets in 
docbook-stylesheets. If I want to be able to automatically get the 
necessary stylesheets, I need to be able to use the catalog definition, 
eg instead of

<xsl:import 
href="../../../tools/docbook-stylesheets/html/chunk-common.xsl"/>

it would use

<xsl:import 
href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-common.xsl"/>

And then the catalog file from the stylesheet dependency would resolve 
that to the correct files. Is there any other reason for the use of 
these relative paths other than the build itself?

3. Similarly, the xml sources define relative paths to the DTD:

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"../../tools/docbook-dtd/docbookx.dtd">

If I'm going to do away with the tools folder, these become invalid. Is 
that a problem? Otherwise I can always add a task that automatically 
downloads and unzips this to that location.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

On 23-6-2018 16:44, Simonov Denis via Firebird-docs wrote:
> Mark Rotteveel <ma...@la...> 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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Simonov D. <sim...@li...>]

Mark Rotteveel <ma...@la...> 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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Norman D. <no...@du...>]

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!

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Köditz, M. <Mar...@it...>]

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 

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Norman D. <No...@du...>]

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'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.

I did think about printing out the HTML User Guide - 340 odd pages 
though, and that's a tad excessive for my little inkjet!

So, enough waffling, I'm thinking that asciidoc(tor) now gets my vote to 
be honest, It's quicker than running XMLMind with Paul's caveats 
obviously. So if we decide to change, I'm all for it.


Cheers,
Norm.

-- 
Norman Dunbar
Dunbar IT Consultants Ltd

Registered address:
27a Lidget Hill
Pudsey
West Yorkshire
United Kingdom
LS28 7LG

Company Number: 05132767

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Paul V. <pa...@vi...>]

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),

That would be a very good thing.

> 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.

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.

(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.

> - 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.

> 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.)

Anyway, I'm very interested!

Cheers,
Paul

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Dmitry Y. <fir...@ya...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Dmitry Y. <fir...@ya...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

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

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Norman D. <No...@du...>]

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 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.

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!

Good work Mark.


Cheers,
Norm.

On 15 June 2018 12:32:26 BST, Mark Rotteveel <ma...@la...> wrote:
>On 15-6-2018 11:26, Alexey Kovyazin wrote:
>> Hello,
>> 
>> I like the result - html docs looks really cool.
>> Also, I think it is more suitable for the translation.
>> 
>> Do you have PDF version to take a look at?
>
>I have now also added PDF versions on 
>https://mrotteveel.github.io/firebird-documentation/ (you may need to
>do 
>a hard refresh due to caching). Again, this is just default without any
>
>Firebird specific styling, etc.
>
>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
>Fir...@li...
>https://lists.sourceforge.net/lists/listinfo/firebird-docs

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

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