#1116 Fix some Naming Guidelines formatting issues
Merged 8 months ago by tibbs. Opened 8 months ago by mcinglis.
mcinglis/packaging-committee naming-formatting-fixes  into  master

@@ -56,14 +56,14 @@ 

  === Separators

  

  When naming packages for Fedora,

- the maintainer MUST use the dash '-' as the delimiter for name parts.

- The maintainer MUST NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.

- Version numbers used in compat libraries do not need to omit the dot '.'

- or change it into a dash '-'

+ the maintainer MUST use the dash `+-+` as the delimiter for name parts.

+ The maintainer MUST NOT use an underscore `+_+`, a plus `+++`, or a period `+.+` as a delimiter.

+ Version numbers used in compat libraries do not need to omit the dot `+.+`

+ or change it into a dash `+-+`

  (see <<Multiple packages with the same base name>>

  for more info on this case).

  

- There are a few exceptions to the no underscore '_' rule:

+ There are a few exceptions to the no underscore `+_+` rule:

  

  * httpd, pam, and SDL addon packages are excluded,

    refer to "`<<_httpd_pam_and_sdl,Addon Packages (httpd, pam, and SDL)>>`".
@@ -140,12 +140,12 @@ 

  

  * The package version, which SHOULD include the periods present in the original version.

  ** If the base package name ends with a digit,

-    a single underscore ("_") MUST be appended to the name,

+    a single underscore (`+_+`) MUST be appended to the name,

     and the version MUST be appended to that,

     in order to avoid confusion over where the name ends and the version begins.

  ** If the base package name does not end with a digit,

     the version MUST be directly appended to the package name with no intervening separator.

- * a hyphen ("-") followed by a descriptive suffix

+ * a hyphen (`+-+`) followed by a descriptive suffix

    such as "stable"

    which provides some indication

    as to the nature of the packaged version.
@@ -184,8 +184,8 @@ 

  case SHOULD only be used where necessary.

  Keep in mind to respect the wishes of the upstream maintainers.

  If they refer to their application as "ORBit",

- you SHOULD use "ORBit" as the package name,

- and not "orbit".

+ you SHOULD use `+ORBit+` as the package name,

+ and not `+orbit+`.

  However, if they do not express any preference of case,

  you SHOULD default to lowercase naming.

  
@@ -209,7 +209,7 @@ 

  == Font Packages

  

  Packages containing fonts must be named

- *[foundryname-]projectname[-fontfamilyname]-fonts*,

+ `+[foundryname-]projectname[-fontfamilyname]-fonts+`,

  in lowercase.

  For a full explanation, see xref:FontsPolicy.adoc#_naming[Packaging/FontsPolicy#Naming].

  
@@ -249,9 +249,9 @@ 

  Packages that rely on Apache httpd, pam, or SDL

  as a parent use a slightly different naming scheme.

  pam and SDL addons use the format: `+%{parent}_%{child}+`,

- with an underscore "_" as a delimiter.

+ with an underscore `+_+` as a delimiter.

  Apache httpd addons use the format: `+mod_%{child}+`,

- with an underscore "_" as a delimiter.

+ with an underscore `+_+` as a delimiter.

  This naming scheme is usually the same as used for the source tarball name.

  

  *Examples:*
@@ -276,23 +276,23 @@ 

  of the emacs component.

  

  Where a component adds functionality to more than one emacs compatible editor,

- the package name SHOULD be of the form emacs-common-$NAME.

+ the package name SHOULD be of the form `+emacs-common-$NAME+`.

  In this case,

  the main package SHOULD contain only files common

  to all emacs compatible editors,

  and the code specific to each SHOULD be placed

- in a subpackage reflecting the specific editor $EDITOR-$NAME

- e.g., xemacs-$NAME, emacs-$NAME

+ in a subpackage reflecting the specific editor `+$EDITOR-$NAME+`

+ e.g., `+xemacs-$NAME+`, `+emacs-$NAME+`

  (the latter being the package specific to GNU Emacs).

  An example of this scheme can be found in the package

- emacs-common-muse.

+ `+emacs-common-muse+`.

  

  Where a component is designed to add functionality

  to only a single emacs compatible editor,

  the main package name SHOULD reflect this

- by being called $EDITOR-$NAME.

+ by being called `+$EDITOR-$NAME+`.

  An example of this situation can be found in the package

- emacs-auctex, which is built only for GNU Emacs.

+ `+emacs-auctex+`, which is built only for GNU Emacs.

  

  *Examples:*

  
@@ -367,34 +367,34 @@ 

  [cols=",,",]

  |=============================================

  | module name |base lua version |package name

- | argparse |(default) |lua-argparse

- | argparse | 5.1 | lua5.1-argparse

- | sql | 5.2 | lua5.2-sql

+ | argparse |(default) | `+lua-argparse+`

+ | argparse | 5.1 | `+lua5.1-argparse+`

+ | sql | 5.2 | `+lua5.2-sql+`

  |=============================================

  

  

  === OCaml modules

  

  OCaml modules, libraries and syntax extensions

- SHOULD be named ocaml-foo.

- Examples include: ocaml-extlib, ocaml-ssl.

+ SHOULD be named `+ocaml-foo+`.

+ Examples include: `+ocaml-extlib+`, `+ocaml-ssl+`.

  

  This naming does not apply to applications written in OCaml,

  which can be given their normal name.

- Examples include: mldonkey, virt-top, cduce.

+ Examples include: `+mldonkey+`, `+virt-top+`, `+cduce+`

  

  === Perl modules

  

  Packages of Perl modules

  (thus they rely on Perl as a parent)

  use a slightly different naming scheme.

- They SHOULD be named perl-CPANDIST

- where CPANDIST is the name of the packaged CPAN module distribution

+ They SHOULD be named `+perl-CPANDIST+`

+ where `+CPANDIST+` is the name of the packaged CPAN module distribution

  (which is almost always also the unit of Perl module packaging).

  In the rare cases when a CPAN module distribution needs to be split

  into smaller subpackages

  e.g., due to dependencies,

- the extra subpackages SHOULD be named perl-CPANDIST-Something.

+ the extra subpackages SHOULD be named `+perl-CPANDIST-Something+`.

  

  *Examples:*

  
@@ -424,7 +424,7 @@ 

  * A source package containing primarily a _Python library_

  MUST be named with the prefix `+python-+`.

  

- The character `pass:[+]` is reserved for

+ The character `+++` is reserved for

  xref:Python.adoc#_extras[Extras].

  

  ==== Python2 binary package naming
@@ -441,7 +441,7 @@ 

  This makes a package name format of `+R-$NAME+`.

  When in doubt, use the name of the module that you type to import it in R.

  

- '''Examples: '''

+ *Examples:*

  

  ....

  R-mAr (R module named mAr)
@@ -451,14 +451,14 @@ 

  

  === Sugar Activities

  

- The name for all packaged Sugar activities must be prefixed with sugar-.

+ The name for all packaged Sugar activities must be prefixed with `+sugar-+`.

  For more details, see xref:SugarActivityGuidelines.adoc[Packaging/SugarActivityGuidelines].

  

  === Tcl/Tk extensions

  

- The name for all packaged Tcl/Tk extensions must be prefixed with tcl-.

+ The name for all packaged Tcl/Tk extensions must be prefixed with `+tcl-+`.

  This rule applies even for Tcl/Tk packages

- that are already prefixed with tcl in the name.

+ that are already prefixed with `+tcl+` in the name.

  For more details, see xref:Tcl.adoc#_naming_conventions[Packaging/Tcl#NamingConventions].

  

  === TeX
@@ -466,7 +466,7 @@ 

  As Fedora has switched TeX environments in the past,

  TeX packages SHOULD not be named after the TeX environment

  (TeX Live or teTeX)

- but instead SHOULD carry the prefix "tex-".

+ but instead SHOULD carry the prefix `+tex-+`.

  

  == Authorship

  

This PR fixes a few formatting issues I noticed in the current Naming Guidelines page:

  1. the "httpd, pam and SDL" section had broken formatting, due to not escaping the _s.
  2. the "R modules" "Examples" was misformatted.
  3. references to package names, fragments, or templates were inconsistently monospaced.

With the aim of allowing expedient review and merging, this PR is focused solely on formatting, and not on content.

Looks good to me. Though I wonder if it wouldn't be easier to consistently use

`+foo+`

style (intended for source code literals that are included verbatim) instead of switching between those and just using simple backticks (which are only markers for using a monospace font, but which don't turn off other formatting). Using the "source code" markup might also be less error prone (because you can't forget to update it to this style when adding some underscores into it, for example).

applicable AsciiDoctor documentation:

rebased onto 38028900915264ad6787d6495273072961a0607a

8 months ago

3 new commits added

  • Fix Naming Guidelines monospace for package names
  • Fix Naming Guidelines R modules examples header
  • Fix Naming Guidelines symbols formatting
8 months ago

@decathorpe Thanks for quick review. I couldn't make my mind up on that, so I appreciate you expressing a preference :smile: I've swapped over to consistent backtick-pluses in the updates.

My concern that inclined me to this first proposal was the sequence:

`+++`

Which, programmer me, couldn't provide a sane explanation for why an asciidoc parser shouldn't treat that as starting a triple-plus macro passthrough sequence. AsciiDoctor does just render as a "+", though, and I figure that's intentional. An alternative would be to use pass:[+] for that, but then that's too bulky to want to use for every symbol, but then that's its own inconsistency.

If we ever need to add monospaced +++ somewhere in our guidelines, we can start arguing about the AsciiDoc spec :) Until then, the PR looks good to me now. :thumbsup:

rebased onto 051dfde

8 months ago

Pull-Request has been merged by tibbs

8 months ago
Metadata