kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

I wanted to update this thread since I am continuing work on the
update/rewrite of the KiCad documentation for V6, and continue to run
into areas where Asciidoc vs Asciidoctor is causing issues.  I want to
move us to Asciidoctor as soon as possible so that we stop wasting
time on these problems and can move forward.

>From discussion with Wayne and others, dropping support for CJK
languages is not an option.  We expect a growing number of KiCad users
whose first language is Chinese/Japanese/Korean in the future and we
do not want to exclude them from the translated documentation.

Right now, I have a working prototype solution for generating HTML and
PDF output from Asciidoctor, with CJK support. [1]
The current plan is to move forward with merging this soon.  This will
have two impacts:

1) ePUB support will be dropped for now.  I recognize that some users
appreciate ePUB support, but the fact is that we have limited
resources to tackle the documentation and I would rather spend that
time actually writing documentation rather than investigating yet
another output format and its quirks.  I think most e-readers can read
HTML and/or PDF files anyway, so hopefully this is not that big a
deal.  We welcome contributions to re-add ePUB support after this is
merged, I just don't have time to do it personally and nobody else has
stepped up yet.

2) We will add a dependence on asciidoctor-web-pdf[1] to generate PDF
files.  This is the recommended path from the Asciidoctor team and
seems to work well.

Again, I recognize that this is an imperfect solution, but overall I
think it will be better for the project to move to Asciidoctor in the
long term, and again we welcome any assistance folks want to offer in
adding back support for ePUB if there is demand for this.

Thanks,
Jon

[1] https://gitlab.com/kicad/services/kicad-doc/-/merge_requests/809
[2] https://github.com/Mogztter/asciidoctor-web-pdf


On Sun, Feb 21, 2021 at 6:24 PM Jon Evans <jon@xxxxxxxxxxxxx> wrote:
>
> By suggestion of someone on the asciidoctor list I tried
> asciidoctor-web-pdf which uses nodejs+puppeteer to create PDFs from
> the document sources.
>
> This seems to work really well and has no issues with CJK fonts.
>
> There are a few warnings generated that need follow-up but this seems
> like a promising approach.
> Sample PDFs (with the default stylesheet) are attached in the MR recent comment:
>
> https://gitlab.com/kicad/services/kicad-doc/-/merge_requests/776#note_513840519
>
> -Jon
>
> On Sun, Feb 21, 2021 at 9:43 AM Jon Evans <jon@xxxxxxxxxxxxx> wrote:
> >
> > Hello Carsten,
> >
> > On Sun, Feb 21, 2021 at 2:34 AM Carsten Schoenert
> > <c.schoenert@xxxxxxxxxxx> wrote:
> > > please keep in mind that the build process in some distributions has
> > > restrictions like no access to resources outside the local machine and
> > > to external packages.
> > > Means e.g. 'gem install foo' will not work. The build must work only
> > > based on packaged stuff.
> >
> >
> > I am not sure what is packaged where, but moving to asciidoctor at all
> > will require new dependencies.  As far as I know, using rubygems
> > should be possible on most distributions, but installing the
> > dependencies with bundler is not going to be part of the build
> > process, just a "shortcut" to installing those dependencies on
> > platforms where it works.
> >
> > Any non-packaged dependencies (such as CJK fonts, which it is looking
> > like we will have to customize) will need to be kept in the docs tree.
> >
> > >
> > > A typical way of dealing with the work is to do the easy stuff first and
> > > work further on the more difficult parts.
> > > So far I see this the build of PDF and EPUB for non Japanese languages
> > > is mostly still working. So I suggest to drop Japanese for now and
> > > document this clearly but also the state why this isn't working again (yet).
> >
> > OK, this is an option, but keep in mind it's not just Japanese, but
> > also Chinese (which is actively maintained by taotieren) that is not
> > possible right now with asciidoctor-pdf.  We would have to drop those
> > PDFs and just maintain the HTML documentation.
> >
> > >
> > > From the maintainer of the Latex related packages in Debian I know that
> > > the Japanese fonts are a bit complicated as unfortunately poorly
> > > maintained. I can ask for detailed status in case some specific font has
> > > some minor issues.
> > >
> >
> > As far as I can tell, the recommended workflow for CJK support in
> > asciidoctor-pdf is to maintain your own font, because the libraries
> > are very picky about font details and using "stock" fonts such as the
> > Noto CJK series (which are popular because they contain very many
> > characters) is not possible.
> >
> > I will ask if there are any alternatives that people are using.
> >
> > -Jon