kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

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