Re: POD formatter version comments
[email protected] ("Ricardo Signes") Sun, 24 Mar 2024 13:46:09 -0400
| Newsgroups | perl.pod-people |
|---|---|
| Message-ID | <[email protected]> |
--16a369e6b0b2404b9ff22544265227cd
Content-Type: text/plain
On Wed, Mar 20, 2024, at 18:34, Karen Etheridge wrote:
> I believe the paragraph in the docs should stay, but change the MUST to a SHOULD, with a proviso that there should be a way to disable it (for the purposes of repeatable builds etc). If the paragraph is removed entirely, no one will implement it (the fact that it is not well-implemented now is sad, but beside the point). I have no strong feelings as to whether the option should default to on or off, but the option should exist for those that wish this extra content.
I don't have strong feelings about using SHOULD here, although mostly I think it's simpler to strike the paragraph.
If the paragraph is removed, nothing will change except some noncompliant formatters might become compliant. Removing the "formatters must" does not imply a "formatters must not", so nobody is being robbed of an option to do this or to keep doing it.
I think a better paragraph, if we don't just delete, might be:
Formatters may introduce comments to their output that provide information on the tooling used to produce that output. When doing this, implementers should consider that reproducible build systems benefit from reduced churn in the build products. This implies that it should be possible to suppress those comments. If the *significant* content of a translation doesn't change between versions, mandatory *insignificant* changes might be a hindrance.
--
rjbs
--16a369e6b0b2404b9ff22544265227cd
Content-Type: text/html
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE html><html><head><title></title><style type=3D"text/css">p.Mso=
Normal,p.MsoNoSpacing{margin:0}</style></head><body><div>On Wed, Mar 20,=
2024, at 18:34, Karen Etheridge wrote:<br></div><blockquote type=3D"cit=
e" id=3D"qt" style=3D""><div dir=3D"ltr"><div class=3D"qt-gmail_quote"><=
div> I believe the paragraph in the docs should stay, but change th=
e MUST to a SHOULD, with a proviso that there should be a way to disable=
it (for the purposes of repeatable builds etc). If the paragraph is rem=
oved entirely, no one will implement it (the fact that it is not well-im=
plemented now is sad, but beside the point). I have no strong feelings a=
s to whether the option should default to on or off, but the option shou=
ld exist for those that wish this extra content.<br></div></div></div></=
blockquote><div><br></div><div>I don't have strong feelings about using =
SHOULD here, although mostly I think it's simpler to strike the paragrap=
h.</div><div><br></div><div>If the paragraph is removed, nothing will ch=
ange except some noncompliant formatters might become compliant. R=
emoving the "formatters must" does not imply a "formatters must not", so=
nobody is being robbed of an option to do this or to keep doing it.<br>=
</div><div><br></div><div>I think a better paragraph, if we don't just d=
elete, might be:<br></div><div><br></div><div class=3D"rjbs-indent" styl=
e=3D"margin-left:40px;">Formatters may introduce comments to their outpu=
t that provide information on the tooling used to produce that output.&n=
bsp; When doing this, implementers should consider that reproducible bui=
ld systems benefit from reduced churn in the build products. This =
implies that it should be possible to suppress those comments. If =
the <i>significant</i> content of a translation doesn't change betw=
een versions, mandatory <i>insignificant</i> changes might be a hin=
drance.<br></div><div class=3D"rjbs-indent" style=3D"margin-left:0px;"><=
br></div><div class=3D"rjbs-indent" style=3D"margin-left:0px;">-- <=
br></div><div class=3D"rjbs-indent" style=3D"margin-left:0px;">rjbs</div=
></body></html>
--16a369e6b0b2404b9ff22544265227cd--