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 <j...@craftyjon.com> 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 <j...@craftyjon.com> 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 <j...@craftyjon.com> wrote: > > > > > > Hello Carsten, > > > > > > On Sun, Feb 21, 2021 at 2:34 AM Carsten Schoenert > > > <c.schoen...@t-online.de> 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@lists.launchpad.net > 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 i...@kipro-pcb.com
-- Mailing list: https://launchpad.net/~kicad-doc-devs Post to : kicad-doc-devs@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-doc-devs More help : https://help.launchpad.net/ListHelp
