Hi Ahmed,
Ahmed Khanzada wrote on Thu, Jul 19, 2018 at 03:57:17AM -0700:
> I am a programmer with a strong passion for both documentation and
> offline computing. Inspired by 9front, I was wondering if there was
> any interest in porting the currently online-only FAQ to an offline
> FAQ format that could perhaps ship with OpenBSD by default, enabling
> a user to have a completely self-documented operating system without
> the need for an Internet connection.
>
> Preferably, this offline FAQ would not be in HTML or anything
> browser-centric, but rather in something like a man format friendly
> for terminal perusing.
I already planned that for years and finally offered one and a half
years ago to do the work of the HTML to mdoc(7) conversion myself
and fully integrate the FAQ into the base system manual pages, as
a new "faq" section alongside the traditional numeric sections.
My arguments were:
1. Easier maintenance.
No more need to update the FAQ in one big step at release time.
Lower risk to lose patches because everything can be committed
at any time. Easier for others to contribute because right
now, nobody knows what exactly has already been written for the
next release.
2. Easier editing.
In particular, mdoc(7) .Xrs and .Sxs are much less cumbersome
to edit than HTML <a>s, and there are a lots of them.
But that applies to almost all markup, even ".Fl x"
is shorter and easier to type than "<b>-x</b>".
3. FAQs for -current become available, not only with spending
no additional maintenance effort, but even reducing effort.
4. The FAQ becomes available offline because it can simply
be installed just like the other manuals.
5. FAQ pages show up in apropos(1).
6. More expressive markup.
All mdoc(7) macros can be used, not just <b> and <i>.
7. Semantic searching.
FAQ pages can be searched for with apropos(1) searches for
specific macro keys.
8. Normal manual pages can more naturally link back to the FAQ
by simply using .Xr rather than .Lk.
9. It's always good to have all documentation available in one
place and with one tool: users will less easily miss the
parts they are looking for.
However, the current FAQ maintainers, tj@ and tb@, vetoed the idea
arguing as follows:
1. They dismissed argument 1, stating they feel it isn't significantly
harder to collect updates non-publicly over time and then commit
them all together at release time than to follow the normal
"only even edit -current" policy used for the source tree at
large, including manual pages.
2. They dismissed argument 2, stating that they personally know
HTML better than mdoc(7) and expect more users to know HTML
than mdoc(7).
3. They dismissed argument 3, saying that the FAQ is mainly for
new users (which i disagree with), these mainly run -stable,
and having a -current FAQ would only cause confusion (which
i don't believe either - quite to the contrary, i often see
confusion because people try to use the FAQ with -current).
4. They dismissed argument 4, saying that they specifically
want to keep the FAQ online-only such that corrections
are instantly visible to users, while offline versions
would retain errors until the next update.
8. They dismissed argument 8, saying that few manual pages
link to the FAQ in the first place.
There was consensus that arguments 5 to 7 and 9 are relevant, but
they considered them less important than the percieved downsides
in arguments 1 to 4.
Given that i highly appreciate the important work tj@ and tb@ do
on the FAQ, i decided to not do the conversion because no matter
what others may think, the people actually doing the work (in this
case the FAQ maintenance) get to decide how they do it. And in
this case, they clearly prefer keeping the FAQ separate and in HTML.
So that is what gets done, even though i almost completely fail to
understand the reasons.
> I would be more than happy to lend my time and efforts to such
> a project, if the community deems it appropriate.
Much appreciated, but unfortunately, that is not sufficient to let
the idea become reality at this point in time. It would be great
if you could start sending patches for whatever issues you find in
both manual pages and in the FAQ, though.
Yours,
Ingo
