Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use RFC 2119 convention to describe package naming convention #26513

Merged
merged 1 commit into from Nov 18, 2018
Merged

Use RFC 2119 convention to describe package naming convention #26513

merged 1 commit into from Nov 18, 2018

Conversation

rht
Copy link
Member

@rht rht commented Jun 11, 2017 •
edited

Motivation for this change

From @a4d442663580's suggestion in #26173 (comment).

Things done
  • Tested using sandboxing
    (nix.useSandbox on NixOS,
    or option build-use-sandbox in nix.conf
    on non-NixOS)
  • Built on platform(s)
    • NixOS
    • macOS
    • Linux
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nox --run "nox-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Fits CONTRIBUTING.md.

@mention-bot
Copy link

@rht, thanks for your PR! By analyzing the history of the files in this pull request, we identified @edolstra, @edwtjo and @vcunat to be potential reviewers.

rht
rht commented Jun 11, 2017
View reviewed changes
doc/coding-conventions.xml Outdated
in new variable names, rather than converted to underscores
(which was convention up to around 2013 and most names
still have underscores instead of dashes) — e.g.,
<varname>http-parser</varname> instead of
<varname>http_parser</varname>.</para></listitem>

<listitem><para>If there are multiple versions of a package, this
should be reflected in the variable names in
SHOULD be reflected in the variable names in
<filename>all-packages.nix</filename>,
e.g. <varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>.
If there is an obvious “default” version, make an attribute like
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this can be more sharply stated as "if there is a version used by the majority/supermajority of the packages, make an attribute like...".

@vcunat
Copy link
Member

vcunat commented Jun 11, 2017

While I'm quite a fan of IETF RFCs, and it will probably be good to utilize their terms to better express strength of obligation, we have docbook here. All-caps words in this way feel rather cumbersome to me personally.

That's contrary to IETF where the pure-ASCII file is the authoritative version...

@vcunat
Copy link
Member

vcunat commented Jun 11, 2017

BTW, if we use something like this, we must define what it means, e.g. via a reference to that RFC.

@Ekleog
Copy link
Member

Ekleog commented Nov 9, 2018

(triage) @rht, do you have an opinion against replacing the ALL CAPS TEXT to bold text, to move this forward?

@rht
Copy link
Member Author

rht commented Nov 10, 2018

Either way is fine as long as it is unambiguous. I have switched the ALL CAPS TEXT to bold text.

@samueldr
Copy link
Member

Rendered:

image

samueldr
samueldr approved these changes Nov 10, 2018
View reviewed changes
Copy link
Member

@samueldr samueldr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Emphasis as italics instead of bold is not an issue, and this is all good IMHO.

@rht
Copy link
Member Author

rht commented Nov 11, 2018

Whoops, I was basing it on https://nixos.org/nixpkgs/manual/#sec-hierarchy, the text "If it’s used to support software development:" has a raw of

     <term>
      If it’s used to support <emphasis>software development</emphasis>:
     </term>

Where it should have been as in https://nixos.org/nixos/manual/release-notes.html#sec-release-18.03

     <emphasis role="strong"> The OpenSSH service no longer enables support for
     DSA keys by default, which could cause a system lock out. Update your keys
     or, unfavorably, re-enable DSA support manually. </emphasis>

@rht
Copy link
Member Author

rht commented Nov 11, 2018

See also: w3c/tr-design#126.

@rht
Copy link
Member Author

rht commented Nov 11, 2018

The raw of https://www.w3.org/TR/payment-request/ does use italic of all caps instead of bold, as in <em class="rfc2119" title="MUST">MUST</em>.

vcunat
vcunat approved these changes Nov 11, 2018
View reviewed changes
Copy link
Member

@vcunat vcunat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, I don't have a strong opinion on the exact "formatting" of the key words. As noted on some links, ALL-CAPS have some advantages like plain text representation (e.g. for clipboard), on the other hand they're not stylistically nice (not a significant issue for short keywords).

I've seen some docbook specs using <glossterm> instead of <emphasis>, but that might be overly complicating and it now renders the same for me anyway.

Overall I'd be inclined to merge with the current style; in the "worst" case we just change it later. Any objections?

doc/coding-conventions.xml Outdated Show resolved Hide resolved
@vcunat
Copy link
Member

vcunat commented Nov 11, 2018

BTW, for the paragraph about non-release versions, I'm personally not confident about the requirement being as hard as must, but I consider that orthogonal to this PR.

@vcunat vcunat self-assigned this Nov 11, 2018
@vcunat
Copy link
Member

vcunat commented Nov 11, 2018

(Self-assigned so that we don't leave this behind again.)

@vcunat vcunat merged commit febadf8 into NixOS:master Nov 18, 2018
vcunat added a commit that referenced this pull request Nov 18, 2018
@vcunat
Merge #26513: docs: use RFC 2119 in a section
a995fc2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@samueldr samueldr samueldr approved these changes

@vcunat vcunat vcunat approved these changes

Assignees

@vcunat vcunat

Labels
8.has: documentation 9.needs: community feedback 10.rebuild-darwin: 0 10.rebuild-linux: 0
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
6 participants
@rht @mention-bot @vcunat @Ekleog @samueldr @GrahamcOfBorg