[Infrastructure] Baseline Requirements - Markdown Output

[Ryan Sleevi]

Thanks Ben. I see you merged it in to master already.

If you were doing that to preview changes, there's an easier way to do
that, before committing. If you look at that URL with the PDF, you'll see
the word "master", which refers to the "master" branch. When you made your
edits, you created a new branch called "Footnote-and-Indenting-Change" (
https://github.com/cabforum/documents/tree/Footnote-and-Indenting-Change )
and a new Pull Request ( https://github.com/cabforum/documents/pull/118 ).

When you created the Branch, you'll see that Travis CI kicked off (it's the
little green arrow next to the commit on that second page). Because it
completed, a preview of your change was available at
https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/Footnote-and-Indenting-Change/BR.pdf

Note how the word "master" has changed to the name of your branch
("Footnote-and-Indenting-Change") in that third URL.

This is how you can preview any of the changes you're making on a branch,
as you're making them. This will hopefully allow easier feedback and making
more comprehensive changes.

One other note, since I saw something quirky about your change - when
merging, you probably want to do "Squash and Merge" instead of "Merge".
https://help.github.com/articles/merging-a-pull-request/ shows how to
select "Squash and Merge" in the interface, with more technical details at
https://help.github.com/articles/about-pull-request-merges/ if you care how
Git/GitHub work. The TL;DR: is that "Squash and Merge" lets you change a
bunch of tiny commits into one 'logical' commit. This is particularly
useful when you're trying to accomplish one 'logical' thing, but may
require several cycles of edit-commit-preview to make sure it's looking
like you'd like. You can make a bunch of those tiny changes, and then just
do "Squash and Merge" at the end to make them a single commit (i.e. "Fix
indenting").

Hope this all helps!

On Tue, Nov 27, 2018 at 12:09 PM Ben Wilson <ben.wilson at digicert.com> wrote:

> For what it’s worth, I edited the Github version to place the footnote for
> “public suffix” adjacent to the paragraph in which it appears and I changed
> “code boxes” to regular indenting so that the lines don’t cut off on the
> right side.
>
>
>
> See
> https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/master/BR.pdf
>
>
>
>
>
> *From:* Infrastructure <infrastructure-bounces at cabforum.org> *On Behalf
> Of *Ben Wilson
> *Sent:* Monday, November 5, 2018 10:02 AM
> *To:* Ryan Sleevi <sleevi at google.com>
> *Cc:* infrastructure at cabforum.org
> *Subject:* Re: [Infrastructure] Baseline Requirements - Markdown Output
>
>
>
> Thanks,  Ryan.
>
>
>
> I think we ought to change what we can (presentation issues) and
> re-generate the PDF.
>
>
>
> Also, I like the way that the automated generation method (not the one I
> used) adds page numbers and doesn’t insert a page break before the section
> headings for the tables.
>
>
>
>
>
> *From:* Ryan Sleevi <sleevi at google.com>
> *Sent:* Monday, November 5, 2018 9:27 AM
> *To:* Ben Wilson <ben.wilson at digicert.com>
> *Cc:* infrastructure at cabforum.org
> *Subject:* Re: [Infrastructure] Baseline Requirements - Markdown Output
>
>
>
> And here are the versions automatically being produced as part of our
> infrastructure:
>
>
>
>
> https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/master/BR.html
>
>
> https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/master/BR.pdf
>
>
>
> I would presume that, in context, we have a couple requirements from the
> past discussions about format:
>
>
>
> 1) A format that folks can edit without the use of/requirement of certain
> platforms and/or third-party software
>
> 2) A format that is stable between versions (i.e. opening in a newer
> version of some software won't change the formatting)
>
> 3) A format that produces stable output (e.g. two different people can
> produce the same output and ensure there aren't visual
> differences/artifacts)
>
>
>
> It's unclear, from the context of requirements, whether there is a fourth
> requirement
>
> 4) Assuming all those things above are equal, a format that minimizes the
> number of steps to produce output should be preferred over other formats,
> on the basis that more steps to produce output creates more opportunities
> for human error or requires more manual intervention
>
>
>
>
>
> Separately, both versions of the documents (what Ben provided and what's
> being produced) 'suffer' from the same formatting issues at present. One is
> the use of footnotes re: "registry-controlled" (which appear at the end of
> the document, rather than the page printed on) and the other is the use of
> block formatting in the profile.
>
>
>
> With respect to the ballots themselves, the footnote is controlled by
> Ballot 96 (
> https://cabforum.org/2013/02/20/ballot-96-wildcard-certificates-and-new-gtlds/
> ) and doesn't require any 'special' treatment - i.e. without requiring a
> new ballot, the presentation of that section 'could' be adjusted. With
> respect to the block formatting (see 5.4.1, 7.1.2.2, 7.1.2.3), that's
> fairly easy to fix and presentational, without changing any of the text.
>
>
>
> I'm specifically avoiding the suggestions of making structural or balloted
> changes to those documents in this WG, given the charter.
>
>
>
> On Mon, Nov 5, 2018 at 10:00 AM Ben Wilson <ben.wilson at digicert.com>
> wrote:
>
> FWIW - Here is what it looks like when I export BR.md to PDF using Typora.
>
>
>
> _______________________________________________
> Infrastructure mailing list
> Infrastructure at cabforum.org
> http://cabforum.org/mailman/listinfo/infrastructure
>
> _______________________________________________
> Infrastructure mailing list
> Infrastructure at cabforum.org
> http://cabforum.org/mailman/listinfo/infrastructure
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20181127/eab6b555/attachment.html>