From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 55E8F21CF25D6 for ; Sat, 8 Jul 2017 14:33:55 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id D68A980465; Sat, 8 Jul 2017 21:35:37 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com D68A980465 Authentication-Results: ext-mx04.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx04.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=lersek@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com D68A980465 Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-90.phx2.redhat.com [10.3.116.90]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8C22477530; Sat, 8 Jul 2017 21:35:36 +0000 (UTC) To: "Kinney, Michael D" References: From: Laszlo Ersek Cc: "edk2-devel@lists.01.org" Message-ID: <641e085b-2797-cc7f-fd0b-97a685c7725c@redhat.com> Date: Sat, 8 Jul 2017 23:35:35 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 MIME-Version: 1.0 In-Reply-To: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.28]); Sat, 08 Jul 2017 21:35:38 +0000 (UTC) Subject: Re: TianoCore-docs GitBook Documentation Process X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 08 Jul 2017 21:33:55 -0000 Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Hi Mike, On 07/08/17 02:37, Kinney, Michael D wrote: > Hello, > > I have added wiki pages that provide an overview of the GitBook documentation > process for TianoCore related documents. These wiki pages are attached to the > EDK II Template Specification repository. The link to the approved RFC on this > topic is also provided. > > https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki > > https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki/TianoCore-Documents-GitBook-Overview#introduction > > I have also added a link to this content from the EDK II Specification wiki page: > > https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Specifications > > Please review and provide feedback if there are steps that are missing or need clarification. This is a large set of articles, it must have been a lot of work! I have four questions/ideas: (1) The article at says, 3. Join the TianoCore-Docs organization on GitHub Can you send an invite? :) On the org page , I looked for a button saying "request an invite" or some such, but came up empty. So what is the github way for joining an organization? I guess the org can send out invites at will, but "solicitation" in the other direction has to occur off-site? (Such as on this mailing list?) (2) The article at explains that there is some kind of (automated) syncing from the tianocore-docs repos to GitBook.com. In case I'm looking at one of the official document git repos on GitHub, such as , what is the fastest way to see an HTML rendered "DRAFT" (matching the master branch) on GitBook.com? Is there some URL pattern that one can compose manually, or is there a way to search for the book quickly on GitBook.com? In , I see 7. Wait a few minutes and verify that the released version of the document has been published by the GitBook server Verify how? Hmmm... OK, so I think I found the links. They are on this page: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Draft-Specification The HTML link patterns are like: https://edk2-docs.gitbooks.io/edk-ii-build-specification/ https://edk2-docs.gitbooks.io/edk-ii-dec-specification/ https://edk2-docs.gitbooks.io/edk-ii-inf-specification/ I think this is a bit cumbersome. What do you think of the following suggestion: in each document source code repository, modify the README.md file so that at the top, it offer a set of links, saying: View this DRAFT specification rendered as: [HTML] -> link points to gitbook.com [PDF] -> link points directly to PDF download from gitbook.com (3) (This is somewhat similar to (2).) Assuming I make a local docs change, and push it to my personal fork on GitHub, how can I review that change on GitBook.com, rendered as HTML (or, say, PDF)? The article at says, 14. Push branch to developer's fork of the documents repository * GitBook project linked to developer's fork of the document can also be setup and used to review the changes and formatting before sending patch review email to the community. How can I do this linking? (I'm aware that a local npm / gitbook toolchain can be used for reviewing the rendered output locally, but I'm curious about this "remote rendering" service too.) In particular, the article at does not say that a developer can, or should, register an account separately on GitBook.com, and set up periodic pulls for his/her personal GitHub repos. Is that how it's supposed to work? (I'm just guessing.) ... Hmmm okay, according to , at least a separate account doesn't appear necessary. Reiterating the above README.md idea, the DeLuxe solution would be if we could place some kind of macro near the top of the README.md file that would automatically point to the GitBook.com rendering of the *referring* repository. So if you clicked the link while viewing an official source repo of the tianocore-docs org, GitBook.com would give you a rendering of that, but if you clicked the same link in a personal src repo, GitBook.com would provide a rendering of *that*. Anyway, this level of automation is not necessary, I'd just like to understand what the most direct way is to get GitBook.com render any branch from either an official docs repo, or a personal docs repo. (4) It would be nice if the (semi-)live renderings on GitBook.com automatically displayed the git commit hash of the source that's been rendered. I see there's a timestamp, for example at : DRAFT FOR REVIEW 04/27/2017 01:14:37 But: there is no time zone, plus I don't know what event that timestamp identifies. Patch authorship date? Patch commit date? Pull date? Rendering date? A commit hash would be better. (Not sure if we can do anything about this; perhaps this would be a new GitBook.com feature.) Sorry if (some of) these questions are already explained in the Wiki, it's quite a bit of info to absorb at once :) Thanks! Laszlo