Bug 264754 - FreeBSD Handbook: Appendix C (Resources on the Internet): updates and corrections
Summary: FreeBSD Handbook: Appendix C (Resources on the Internet): updates and correct...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: Sergio Carlavilla Delgado
URL: https://github.com/freebsd/freebsd-do...
Keywords:
Depends on:
Blocks: 260968 handbook-2022
  Show dependency treegraph
 
Reported: 2022-06-18 17:24 UTC by Graham Perrin
Modified: 2023-10-08 00:59 UTC (History)
3 users (show)

See Also:


Attachments
Screenshot of content to which readers of the FreeBSD Handbook are directed (390.44 KB, image/png)
2023-10-08 00:59 UTC, Graham Perrin
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Graham Perrin freebsd_committer freebsd_triage 2022-06-18 17:24:35 UTC
<https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mailfiltering>: 

> C.2.4. Filtering on the Mailing Lists

> … If an email contains both an HTML and a plain text version, 
> the HTML version will be removed. …

Not so, at least not for freebsd-questions. 

Please see, for example, the two content types text/plain and text/html at <https://lists.freebsd.org/archives/freebsd-questions/2022-June/001399.txt>
Comment 1 Graham Perrin freebsd_committer freebsd_triage 2022-06-18 20:07:29 UTC
Maybe mention that attachments might be not visible with FreeBSD-hosted archives. 

Compare: 

<https://markmail.org/message/6xf44qzwa3seg5da>

* two visible attachments

<https://lists.freebsd.org/archives/freebsd-current/2022-June/002106.html>

* attachments mentioned, but not visible.
Comment 2 Graham Perrin freebsd_committer freebsd_triage 2022-06-18 20:10:01 UTC
> … Only certain types of attachments are allowed on the mailing lists. 
> All attachments with a MIME content type not found in the list below 
> will be stripped before an email is distributed on the mailing lists. …

(In reply to Graham Perrin from comment #1)

Both attachments, neither one stripped, are of a type that is not list: 

application/x-shellscript
Comment 3 Graham Perrin freebsd_committer freebsd_triage 2022-06-26 19:13:25 UTC
Two cherry-picks from recent discussion, the second of which helps with comment #0

<https://markmail.org/message/2ueydxm22v23cxcb> from imp@

> … Most of the advice in appendix c is dated and doesn't really match 
> what people do on the lists. …

<https://markmail.org/message/zyjdxug45xgzjz2b> from bapt@

> Note that the mailing list engine will reject html only email, 
> html is fine as long at it is created with text/plain alternative.
> 
> Note that only the text/plain alternative will be used to construct 
> the archive, …
Comment 4 Fernando Apesteguía freebsd_committer freebsd_triage 2022-10-09 16:07:25 UTC
^Triage: reporter is committer, assign accordingly.
Comment 5 Graham Perrin freebsd_committer freebsd_triage 2022-12-30 11:59:41 UTC
Triage, batch edit (just one): 

* for twenty-eight FreeBSD Handbook-related reports that had gained a 
  personal assignee, prior group/list assignee doc@ was 
  missing from the CC list.

Gentle hint: <https://wiki.freebsd.org/Bugzilla/> ▶ do, don't …
Comment 6 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2023-07-14 14:19:11 UTC
Graham, what would be left here to do exactly?
Comment 7 commit-hook freebsd_committer freebsd_triage 2023-07-15 17:15:39 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=b64d67b51b62e5459f00889d4fb02437a9a7c1de

commit b64d67b51b62e5459f00889d4fb02437a9a7c1de
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 16:51:45 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 16:51:45 +0000

    Handbook: Internet resources: misleading content

    For each list, there is more than one unsubscription option.

    A URL is not found at the bottom of every email received from the list.
    That approach ceased maybe two years ago.

    https://bugs.freebsd.org/264754

    PR: 264754

 documentation/content/en/books/handbook/eresources/_index.adoc | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)
Comment 8 commit-hook freebsd_committer freebsd_triage 2023-07-15 17:15:41 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=e3c5bb8d423f719b7e15fce6f52e6364f486b6a6

commit e3c5bb8d423f719b7e15fce6f52e6364f486b6a6
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 16:43:22 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 16:43:22 +0000

    Handbook: Internet resources: unreal mailto: URLs

    listname@freebsd.org and listname+unsubscribe@freebsd.org are unreal.
    Do not misrepresent them as mailto: URLs.

    https://bugs.freebsd.org/264754

    PR: 264754

 documentation/content/en/books/handbook/eresources/_index.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Comment 9 commit-hook freebsd_committer freebsd_triage 2023-07-15 17:15:42 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=9ea0239364177171761eb1af3ddb1709aedf22de

commit 9ea0239364177171761eb1af3ddb1709aedf22de
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 17:00:35 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 17:00:35 +0000

    Handbook: Internet resources: misplaced directions

    Direction about what type of content to post does not belong under 'How
    to Subscribe'.

    Whilst moving text, be more assertive about subscription to
    freebsd-announce@

    https://bugs.freebsd.org/264754

    PR: 264754

 documentation/content/en/books/handbook/eresources/_index.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
Comment 10 Graham Perrin freebsd_committer freebsd_triage 2023-07-15 17:37:41 UTC
A commit in branch main omitted the PR: prefix when referencing this bug report. 

<https://github.com/freebsd/freebsd-doc/commit/3347f0b50b335ca93281f46a68550944e6c3bf82>

Handbook: Internet resources: list archives

Make the FreeBSD-provided search interface primary.

Add MarkMail.
Comment 11 commit-hook freebsd_committer freebsd_triage 2023-07-15 17:44:50 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=577aeec41099703a861aaf8747387ca0d4d9cb39

commit 577aeec41099703a861aaf8747387ca0d4d9cb39
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 17:32:02 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 17:32:02 +0000

    Handbook: Internet resources: text/html reality

    Make what's stated closer to the reality of what happens when a
    multi-part email message includes text/plain and text/html parts.

    Opening comment 0 at
    https://bugs.freebsd.org/264754#c0

    PR: 264754

 documentation/content/en/books/handbook/eresources/_index.adoc | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)
Comment 12 Graham Perrin freebsd_committer freebsd_triage 2023-07-15 17:53:23 UTC
(In reply to Graham Perrin from comment #10)

(In reply to Sergio Carlavilla Delgado from comment #6)

<https://lists.freebsd.org/search> was recently promoted without the promoter(s) describing it as experimental. 

Should we cease to describe it as experimental under <https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail>?
Comment 13 commit-hook freebsd_committer freebsd_triage 2023-07-15 18:09:56 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=0940974b0a430198f4306ffbaec0af9aeac006b2

commit 0940974b0a430198f4306ffbaec0af9aeac006b2
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 18:07:07 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 18:07:07 +0000

    Handbook: Internet resources: {freebsd-test}

    {freebsd-test} requires a 'the' prefix.

    Whilst fixing the omission, reword the sentence.

    https://bugs.freebsd.org/264754

    PR: 264754

 documentation/content/en/books/handbook/eresources/_index.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Comment 14 commit-hook freebsd_committer freebsd_triage 2023-07-15 18:44:59 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=197d8926fc8b21573d271cf1a86c77c2030e5a52

commit 197d8926fc8b21573d271cf1a86c77c2030e5a52
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 18:36:33 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 18:36:33 +0000

    Handbook: Internet resources: opening paragraphs

    It's no longer realistic to count USENET amongst the top three media
    for effective reach.

    Rewrite the first two paragraphs. Some of what's here belongs elsewhere
    in the FreeBSD Handbook, but it's a start.

    https://bugs.freebsd.org/264754

    PR: 264754

 .../content/en/books/handbook/eresources/_index.adoc       | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
Comment 15 commit-hook freebsd_committer freebsd_triage 2023-07-15 18:54:01 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=ac264ddaa62a592757c3651936307227a1469153

commit ac264ddaa62a592757c3651936307227a1469153
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2023-07-15 18:50:20 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2023-07-15 18:50:20 +0000

    Handbook: Internet resources: correctness

    The Users’s Handbook is not a thing. Rewrite this list item.

    In the subsequent line, FreeBSD Foundation requires a 'The' prefix.

    https://bugs.freebsd.org/264754

    PR: 264754

 documentation/content/en/books/handbook/eresources/_index.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Comment 16 Graham Perrin 2023-10-08 00:59:46 UTC
Created attachment 245492 [details]
Screenshot of content to which readers of the FreeBSD Handbook are directed

Closing note, from the reporter of this bug: my pull request included the attached screenshot.

IMHO, it's no longer appropriate for the FreeBSD Project to steer readers towards areas such as these, but that's just my humble opinion, as a person who has no interest in things such as GBL or GHB.