[noise] spectemplate / spectools

[Trevor Perrin]

On Wed, Nov 15, 2017 at 10:03 AM, David Wong <davidwong.crypto at gmail.com> wrote:
>>  * If you copy the files from spectemplate into your repo (at least
>> the Makefile), then anyone can checkout your repo [1] and build.
>
> They still need the spectools repo right : o ? I figured rather than
> including them in my repo I would just link to the spectools and
> spectemplates repo (like that I don't need to track updates there)

Yeah, but if you're working with specs you already have spectools.

Right now I have to checkout your repo, then:
 - copy Makefile in
 - copy my.bib in
 - edit Makefile to replace "spectemplate" with "disco"

For working with multiple specs, it would be easier if all spec repos
are directly buildable.

The Makefile won't change often - changes are more likely in
spectools.  If the Makefile does change in spectemplate, or needs
local changes, then it would be better to have the correct Makefile
checked in.

So it shouldn't be a big deal to carry the Makefile and my.bib (where
you put local bibtex references).


>>  * Handling of references still needs to be adjusted.
>
> Are you talking about the mentions to the Noise and Strobe specs? I
> thought it was more practical to have them as links instead of bottom
> of the page reference

We should handle references consistently across all specs, however we do it.

As for direct links vs endnotes:  Direct links don't work when
printed.  Also, direct links don't work for everything (e.g.
references to old papers, or books).  And with endnotes you can see
what the reference is without following it.

So while it's more work, I think endnotes is the better approach.  Of
course, this still allows hyperlinks in the endnotes, it's just an
extra click.


>>  * Change log seems like a good idea, probably we should have that in
>> the Noise spec and in spectemplate as well.  I'd put it towards the
>> end of the doc though, so that as it grows (or gets removed later) it
>> doesn't alter pagination throughout the document.  In the
>> spectemplate, maybe put it after "Rationales" but before
>> "Acknowledgements"?
>
> I did what TLS 1.3 did, which is practical in some sense: when you
> check a new version you can scroll directly to the changelog. I will
> reconsider that in the next revision though.

There's a table of contents with internal links, so it's pretty easy
to skip to the Change log either way.

If it's earlier it affects the section numbering and pagination more.
Since it's going to keep growing (changes pagination) and might be
deleted later (changes section numbers) I think the end is better.


>>  * You mentioned "extending" metadata:
>>
>> """
>> extending:
>>  - noise-revision-33
>>  - strobe-v1.0.2
>> """
>>
>> I kind of think displaying those as raw strings will look ugly and
>> cluttered.  Also, I'm not 100% sure what the benefits are.
>
> it's nice to see if the version of the Disco spec is up-to-date with
> the specs of Noise and Strobe you can find on their resp. webpages (or
> lagging behind).

I see, the revision/version numbers are the important part.


> (Some revisions might break Disco for example.) Where do you think
> this should be mentioned in the extension if not in the metadata?

You could just mention them in the text (Overview or wherever?).

Don't have a strong opinion, but still not sure how we'd make this
look good as a special field (in the PDF, we can cram
revision/data/status on one line, but this would probably need a whole
bunch of other lines).

You should maybe suggest a PR (edit the HTML and LaTeX templates, and
your metadata), so we can see this fleshed out.

Trevor