On 17-01-2020 15:00, Alex Peshkoff via Firebird-devel wrote:
On 2020-01-17 16:29, Mark Rotteveel wrote:
Hardly any of the documentation in the docs-folder have links, and you
can have links in Markdown.
No named paragraphs. I have no idea how to create a link to specific
paragraph in MD.
The GitHub-flavoured markdown uses
[<descriptive name>](#<section-name>), where <section-name> is the
lowercase form of the section title, with the spaces replaced by a minus
(-). It looks like that is the standardized form (though I'm not 100%
sure of that).
Pandoc also supports: [<section title>], which I currently use with
Jaybird, but that isn't supported by GitHub.
And if having HTML is important, I'd suggest to write the docs in
markdown (or maybe asciidoc) and generate HTML as part of the build
(eg using pandoc). That is what most other opensource projects do
these days. For good reasons: authoring and diffing is easier compared
to HTML
I can agree with diffing. But what about authoring... Nobody makes you
write HTML as plain text. Dozens of tools exist for it starting with
libreoffcie.
Authoring in plain text is a lot simpler, all you need is a simple text
editor (though if you want, there are those that also render a preview
for you). It avoids spurious changes because your tooling suddenly
decides to generate different HTML (which happened to me regularly with
the old Jaybird release notes when updating OpenOffice or
LibreOffice.org), or because another contributor uses a different tool
for authoring. Or spurious line length changes because of a different
configuration. For example the doc-building how-to is written with a
line-length config of 100, while the doc-writing how-to is written with
a line-length config of 78, which btw is a problem I had last week when
editing both.
, more powerful in its output option compared to 'just' plain text,
and readable both in source form and in rendered output.
What a need to read HTML in source?
When you diff, you need to read the source. And markdown is readable
both in plain text and in rendered output. That means that even if you
only look at the raw source, it is still readable.
Compare
https://raw.githubusercontent.com/FirebirdSQL/jaybird/master/src/documentation/release_notes.md
with
https://raw.githubusercontent.com/FirebirdSQL/jaybird/Branch_2_1/src/etc/release_notes.html
Mark
--
Mark Rotteveel
Firebird-Devel mailing list, web interface at
https://lists.sourceforge.net/lists/listinfo/firebird-devel
