From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.groups.io with SMTP id smtpd.web11.2688.1603183355371130365 for ; Tue, 20 Oct 2020 01:42:35 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=VD9ne/2f; spf=pass (domain: redhat.com, ip: 216.205.24.124, mailfrom: lersek@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1603183354; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=J9FtjjNFKI7vwj2a5uw+KA4mOiotRsZRhV3ba3MK4eM=; b=VD9ne/2fmVe5AIxW302Xwka6FGaSJpYsoFiUjTMxKW/gZU73QPUIOAtC3nvGRIUxN7fhN0 0Bwg96hrg3mXCk9OjmEqdyEqoZp4ouj3vV63B1olXqCQ+2mcw39rMITzENvmmNIbq/+qIJ BnFMDOChe+YuwH560/Y4ic6HieTA2aE= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-369-8DFkdLIvNPibvyiuinyvyA-1; Tue, 20 Oct 2020 04:42:30 -0400 X-MC-Unique: 8DFkdLIvNPibvyiuinyvyA-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 74E6D18C89CA; Tue, 20 Oct 2020 08:42:29 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-114-240.ams2.redhat.com [10.36.114.240]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8ED1260BF3; Tue, 20 Oct 2020 08:42:28 +0000 (UTC) Subject: Re: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI) To: "Kinney, Michael D" , "devel@edk2.groups.io" References: <499b75ab-a015-9d5d-f383-780c66338d4d@redhat.com> From: "Laszlo Ersek" Message-ID: <15be815b-0af5-6646-3fa6-1429bb0ea8b2@redhat.com> Date: Tue, 20 Oct 2020 10:42:27 +0200 MIME-Version: 1.0 In-Reply-To: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=lersek@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit On 10/19/20 22:33, Kinney, Michael D wrote: > Laszlo, > > Yes. As a quick implementation, I am converting the source branch name to a directory > name below gh-pages to store the draft and multiple releases in the single gh-pages > branch. I could add more logic to use better path names if you think that is > required. No, the current names make sense. Thanks for the explanation. > > I agree it would be good if we could get the one fix for PUML up streamed to GitbookIO. > If you look at the following Readme you will see it is no longer maintained. > > https://github.com/GitbookIO/gitbook > > We are using the majority of the content from the GitbookIO projects, Only the > one gitbook plugin for PUML support is being pulled from a fork. > > This does means we need to handle any future issues ourselves, and if that becomes > too much work, we would have to consider a conversion to a different publishing > service or a different document source format. > > The current proposal here is a stop gap to make sure the offline documentation > is made available to the EDK II Community. I agree completely. Introducing this small "external dependency" still leaves us in a lot better situation than what we're in now (which is "no offline docs"). Thanks for the explanation, and for your work on this! Laszlo > > Thanks, > > Mike > > >> -----Original Message----- >> From: Laszlo Ersek >> Sent: Monday, October 19, 2020 12:00 PM >> To: devel@edk2.groups.io; Kinney, Michael D >> Subject: Re: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI) >> >> On 10/16/20 05:48, Michael D Kinney wrote: >>> Hello, >>> >>> I have been working on addressing the gaps in the transition to >>> the new GitBook services for the TianoCore documents in the GitBook >>> markdown format. The major gap is the loss of the offline PDF, >>> EPUB, and MOBI formats. >>> >>> I have found a GitHub action that performs the equivalent work >>> of the legacy GitBook server and it supports publishing the HTML, >>> PDF, EPUB, and MOBI formats in a gh-pages branch of a GitBook >>> document repository. The gh-pages branch supports the HTML >>> web view of the documents and is stored as part of the same >>> GitHub repository that hosts the document source files. >>> >>> I have tried this out on the edk2-TemplateSpecification document >>> in the Tianocore-Docs GitHub organization. >>> >>> https://github.com/tianocore-docs/edk2-TemplateSpecification >>> >>> The following is the link to the GitHub actions YML file that >>> publishes a draft version of the document from the master branch >>> and the release versions of the document from and release/* branch. >>> >>> https://github.com/tianocore-docs/edk2-TemplateSpecification/blob/master/.github/workflows/gitbook-action.yml >>> >>> GitBook Action: >>> * Source: https://github.com/ZanderZhao/gitbook-action >>> * Docs: https://zlogs.net/gitbook-action/ >> >> Does the above mean that the "GitHub actions YML" file produces a new >> commit on the gh-pages branch, generated at a particular state >> (checkout) of the master branch? >> >> Also, where is the PDF format stored? >> >>> >>> I found a few issues with the support of embedded PlantUml >>> diagrams. A fork of the GitBook puml plugin is available >>> that addresses these issues. The book.json file is updated >>> to use this newer plugin. >>> >>> "plugins": ["puml-aleung"], >>> >>> Links to the GitBook puml pluigis: >>> >>> Original: https://github.com/GitbookIO/plugin-puml >>> Updated: https://github.com/aleung/gitbook-plugin-puml >> >> It would be nice if the updates could be upstreamed from aleung's space >> to GitbookIO. >> >>> >>> The following are the links to the EDK II Template Specification >>> documents published by this Gitbook Action. Notice that all the >>> links are to files in either GitHub repos or the web pages published >>> by GitHub when a gh-pages branch is present and updated. >>> >>> Draft versions from master branch: >>> >>> HTML: https://tianocore-docs.github.io/edk2-TemplateSpecification/master >> >> Ugh, confusing. It says "master". I guess it still consumes the >> "gh-pages" branch. >> >>> PDF: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.pdf >> >> Hmmm. This seems to answer multiple of my questions above. Indeed this >> binary PDF file exists in the original repo, it is on the gh-pages >> branch, and "master" is a pathname component (likely showing the branch >> name that provided the markdown source code for the rendering). >> >>> EPUB: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.epub >>> MOBI: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.mobi >>> >>> Release versions from release/0.2 branch: >>> >>> HTML: https://tianocore-docs.github.io/edk2-TemplateSpecification/release-0.2 >>> PDF: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/release-0.2/mybook/ebook.pdf >>> EPUB: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/release-0.2/mybook/ebook.epub >>> MOBI: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/release-0.2/mybook/ebook.mobi >>> >>> In order to enable this on all the documents in Tianocore-docs, the >>> following tasks need to be performed on each document repo: >>> * Update book.json in master and release/* branches to use the >>> newer PlantUML plugin. >> >> Again, upstreaming to GitbookIO would be nice. At this time, >> >> https://github.com/aleung/gitbook-plugin-puml >> >> reports >> >> "This branch is 2 commits ahead of GitbookIO:master" >> >> hmmm... oh wait, the relevant commit is also the subject of PR#8 for >> GitbookIO/plugin-puml: >> >> https://github.com/GitbookIO/plugin-puml/issues/8 >> >> So why was that PR abandoned?... >> >>> * Add the file .github/workflows/gitbook-action.yml to the >>> master and release/* branches. >>> * Force a document build on the master and release/* branches to >>> publish all draft and release versions of the documents. >>> >>> Please review the content here and the published documents and let >>> me know if there are any concerns with switching to a GitHub >>> Action to publish all Tianocore Gitbook markdown based documents. >> >> Thank you for researching this! >> >> My only concern is that I'd prefer our action scripts to consume >> https://github.com/GitbookIO rather than https://github.com/aleung/ , in >> the long term. I'd think the former should give us better support in the >> long term -- although, that may be a foolish hope, given that the >> PlantUml diagrams issue is only fixed in the latter, at the moment :/ >> >> Can we somehow talk to Leo Liang? I think we should understand why the >> PlantUML fix is not part of the offical GitbookIO repo. >> >> Thanks! >> Laszlo >