kicad-doc-devs team mailing list archive

[Seth Hillbrand <seth@xxxxxxxxxxxxx>]

Also, we will be creating and hosting the PDF files on the kicad.org
website.  Distributions that do not/can not build PDF documentation using
the gem toolchain but still wish to distribute the PDF files, will be able
to package the generated files.

-Seth

On Thu, May 20, 2021 at 8:02 AM Jon Evans <jon@xxxxxxxxxxxxx> wrote:

> 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
>
> --
> Mailing list: https://launchpad.net/~kicad-doc-devs
> Post to     : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-doc-devs
> More help   : https://help.launchpad.net/ListHelp
>


-- 
[image: KiCad Services Corporation Logo]
Seth Hillbrand
*Lead Developer*
+1-530-302-5483‬
Long Beach, CA
www.kipro-pcb.com    info@xxxxxxxxxxxxx