kicad-doc-devs team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxxx>]

On Sat, Feb 20, 2021 at 06:56:13PM -0500, Jon Evans wrote:
> Hi all,
> 
> I'm going to try to get the work Johannes started[1] complete so we can
> move to asciidoctor.
> 
> Right now the main blocker is CJK font support. You can see more details on
> the MR; I'm going to reach out to asciidoctor community to see if anyone
> has a working solution for this other than the unmaintained KaiGen Gothic
> package (this font doesn't even seem to be very available anymore).
> 
> One question: do we really need to maintain PDF and ePUB support?  I would
> honestly rather spend time writing documentation than working on the bugs
> associated with the multiple format build system, but I will keep working
> on it if there is a good reason to.
> 
> It would not be that unusual for us to distribute the manuals in HTML form
> for offline viewing, and focusing only on HTML would let us get the HTML
> style looking good and not worry about any inconsistencies between other
> formats.
> 
> Thoughts?  I don't know the history of PDF and ePUB being offered as doc
> formats so I don't know if there is a good reason to offer them instead of
> HTML.
> 
> -Jon
> 
> [1] https://gitlab.com/kicad/services/kicad-doc/-/merge_requests/776

My thoughts:

1) I would not drop epub & pdf. Those are very useful formats for when
you want to document away from your computer. For example I myself use _a
lot_ my ebook reader kindle and having the possibility to use my free
time to revise or read about some useful commands in KiCad is invaluable.

2) another (partially) missing feature of asciidoc* is the lang=xx
parameter support. That option, passed like -o lang=xx like it was with
asciidoc won't work but the funtionality is there almost complete. See:

https://docs.asciidoctor.org/asciidoctor/latest/localization-support/

if you do a:

ls $(dirname $(dirname $(gem which asciidoctor)))/data/locale

you'll see that all language definition files are already distributed
with the asciidoctor package. You just have to refer to that dir to make
the asciidoctor compiler see them.

--

Saluton,
Marco Ciampa