Page MenuHomeFreeBSD

Download FreeBSD: headings, redundancy, clarity

Authored by grahamperrin on Nov 2 2022, 4:22 AM.
Referenced Files
Unknown Object (File)
Thu, May 18, 11:35 PM
Unknown Object (File)
Thu, May 18, 11:23 PM
Unknown Object (File)
Sun, May 7, 1:55 AM
Unknown Object (File)
Tue, May 2, 8:10 AM
Unknown Object (File)
Apr 2 2023, 6:23 AM
Unknown Object (File)
Mar 18 2023, 5:45 AM
Unknown Object (File)
Mar 11 2023, 6:29 AM
Unknown Object (File)
Mar 5 2023, 6:03 PM



Level 1 heading 'Download FreeBSD' is not perceptibly different from the identically-worded visible title with a single sentence between the two. This heading appears to be redundant.

The very short 'Help to Test' section is no more than direction to visit the download page. Nonsense, we're already at the download page.

Generally, the page has become a slightly disorderly mix: choices, production quality (RELEASE), beta, development, snapshots, CURRENT, STABLE, general information, purchasing (RELEASE, presumably), archaic stuff, current stuff (derivatives (non-Project)), current stuff (ports (within the FreeBSD Project)). Begin improving this, partly through adjustments to heading levels.

Two new headings, level 1:

Production Quality

Development and Testing

… and so on.

Test Plan

Diff Detail

R9 FreeBSD doc repository
Lint Not Applicable
Tests Not Applicable

Event Timeline

grahamperrin created this revision.

I forgot, Americanisation. should probably be uppercase Q in a heading.


… should probably be Testing (uppercase T) in a heading.

The Development and Testing preamble is intentionally terse, but (necessarily) slightly technical. Essentially:

  • drop a hint that release is not always (production quality) release
  • drop a hint to reduce the likelihood of people aiming for something current, i.e. latest, without understanding the special meaning of the word.

There's the temptation to say more in this preamble, let's not.

(More can be said, and pictured, elsewhere.)


Superflous; delete.

Already stated: not intended for use in production environments added inline comments.

"prerelease", to me, implies "being actively prepared for actual release". Hence, BETA-n and RC-n are, -current definitely isn't by my lights. I have no opinion about -stable inbetween minor releases. Perhaps "Versions not intended for use..."?


I don't think we have user-visible alphas at this time.


I'd also mention -STABLE here.

(And "People looking for the... most likely want... " to avoid "you".)


I'd link to the Handbook here for an explanation.


Should that even be on this page, instead of under

Approved, regardless of in-line comment above.


We can probably get rid of the NFS reference here.

This revision is now accepted and ready to land.Nov 2 2022, 1:54 PM
grahamperrin added inline comments.

For 13.1, PRERELEASE preceded BETA1.

That's not intended to answer the question, however it might be a good example of ways in which FreeBSD can surprise people.

Certainly, we can improve people's understandings by having clearer explanations – anything in-depth can be kept away from the 'Get FreeBSD' page – but for now, I reckon, it's true enough to state that a release candidate is not intended for use in production.

I'll enjoy a longer conversation about this, maybe in IRC. Thanks, folks.


True, however this is general text – intentionally not changing, conditionally, when things appear then disappear.


RELEASE is likeliest.

In this case, wording is intentionally personal.


Restraint here was intentional.

The page already begins with a general link to Release Information | The FreeBSD Project, where links to the FreeBSD Handbook – for STABLE and CURRENT – are fairly prominent.


Done at, it'll be included when I push to freebsd HEAD:main.

There remains a "Huh?" aspect to this section of the page, we can aim to make things crystal clear at a later date.


I do plan to:

  1. improve About FreeBSD Ports | The FreeBSD Project, by (at least) moving the essence of what's highlighted
  2. further condense this download/get/where page by moving the essence of some other content (e.g. the derived/distro stuff).

The restraint here in D37235 was to simplify review, and so, expedite approval. Essentially:

  • the duplicate headings, obviously wrong, which have annoyed me for a long time
  • the self-referencing nonsense, which stuck out like a sore thumb when I thought of preparing for links to 12.4-RELEASE.

Looking ahead:

  • aim for this page to convey, more clearly, in as few words as possible:
    • what you get with the OS
    • what's additional (not included)
    • where to get additions
  • assume that some readers will be blind to the sidebar (with Ported Applications at its foot, but nothing about getting stuff that's based on the OS)
  • more broadly, assume no sidebar.
This revision was automatically updated to reflect the committed changes.
grahamperrin marked 6 inline comments as done.

For a future revision: instead of Download FreeBSD, a better title for the page might be Get FreeBSD. This would, at least, match the phrase that's used at the home page to link here.

(Some of what's here – purchasing a disc from FreeBSD Mall, for example – does not involve any download by the reader.)

The title was no different at the time of migration to Hugo and AsciiDoctor. I wonder whether it was Get FreeBSD at any time prior to that, I don't intend to dig.


Post-commit, a cosmetic issue: no visible white space between the table and the level 1 heading that's below.

image.png (471×316 px, 24 KB)

5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd must be fixed, I'll open a simple review for the heading section levels alone.


Post-commit, a cosmetic issue: again, white space (an empty line) marked up, but no visible white space above what I thought was a level 1 heading:

image.png (117×222 px, 10 KB)

Now, reading Markdown syntax alongside, I see:

  • Markdown for level 1 (headings) is treated as level 0 (section) in AsciiDoc

– and section 0, equal to a title, must occur no more than once in an article, and so on.

Three comments done, through faba218b9283 for D37307.

Styles of headings

Now, looking at Get FreeBSD | The FreeBSD Project: to my eye, the styles of heading levels 2 and 3 (resulting from AsciiDoc section levels 1 and 2) are no different from the style of heading 1 for the title. I'll have a chat, initially with @carlavilla, about possible future enhancements in this area.

Reviews and content

@gjb thanks again for approvals (and for mentoring) at so busy a time. faba218b9283 omitted to show you as (mentor), sorry.

@pauamma thanks again for suggestions, particularly around the meanings of prerelease et cetera. For discussions ahead of future reviews, we should rope in @koobs and others – Kubilay is, memorably, given credit for the second of the images at