Huh? I thought the Doc project was moving away from raw DocBook XML to something a bit more human-friendly. DocBook is really designed with tooling in mind: it expects you to be using a semantic document editor and is incredibly painful to edit with a text editor. Unfortunately, I’ve never actually seen a decent DocBook editor and I was too lazy to write one.
The suggestions about configuring your editor in this are horrible. XML is a machine-readable file format. If you want it to be formatted in a specific way in the repo (which you may for nice diffs, for example) then provide an automatic formatter. Unfortunately, the FreeBSD docs style is not designed to produce nice diffs, it’s designed to look good on a specific terminal with specific editor configurations. If you want nice diffs, you want to mandate a line break after every sentence, so that editing one sentence will not include any other sentence in the diffs. With the FreeBSD docs style, it will re-flow the entire paragraph, making code review painful without additional tooling.
Huh? I thought the Doc project was moving away from raw DocBook XML to something a bit more human-friendly. DocBook is really designed with tooling in mind: it expects you to be using a semantic document editor and is incredibly painful to edit with a text editor. Unfortunately, I’ve never actually seen a decent DocBook editor and I was too lazy to write one.
The suggestions about configuring your editor in this are horrible. XML is a machine-readable file format. If you want it to be formatted in a specific way in the repo (which you may for nice diffs, for example) then provide an automatic formatter. Unfortunately, the FreeBSD docs style is not designed to produce nice diffs, it’s designed to look good on a specific terminal with specific editor configurations. If you want nice diffs, you want to mandate a line break after every sentence, so that editing one sentence will not include any other sentence in the diffs. With the FreeBSD docs style, it will re-flow the entire paragraph, making code review painful without additional tooling.
I think they want to convert to a diff. format but nobody has put in the time/effort to get it across the finish line.