Offline FAQ

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Offline FAQ

Ahmed Khanzada
Hello,

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 would be more than happy to lend my time and efforts to such a project, if
the community deems it appropriate.

-- Ahmed Khanzada

Reply | Threaded
Open this post in threaded view
|

Re: Offline FAQ

Jacqueline Jolicoeur
On Jul 19 03:57, Ahmed Khanzada wrote:

> Hello,
>
> 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 would be more than happy to lend my time and efforts to such a project, if
> the community deems it appropriate.
>
> -- Ahmed Khanzada
>

Why not simply use cvs and a terminal browser from packages/ports
(w3m, links+, lynx) to view the faq offline?

$ cvs checkout -P www/faq
$ w3m www/faq/index.html

Reply | Threaded
Open this post in threaded view
|

Re: Offline FAQ

Ingo Schwarze
In reply to this post by Ahmed Khanzada
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

Reply | Threaded
Open this post in threaded view
|

Re: Offline FAQ

lists-2
In reply to this post by Ahmed Khanzada
Thu, 19 Jul 2018 03:57:17 -0700 Ahmed Khanzada <[hidden email]>
> Hello,
>
> 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.

Hi Ahmed,

You can be sure you are not the only one.  Yes indeed, there is interest
in having the system include all necessary documentation to use offline,
immediately after the installation every important information included.

The key here is: important to have while all offline reducing ambiguity.
The manuals are also available online, via the man.openbsd.org web site.

> 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.

There is absolutely a necessity for getting started manual page for each
section, typically called intro.  I imagine the bits that can not be put
in the respective manual page could be placed in an extra(section) page.

Use the name you think appropriate: book, guide, index, faq, extra, etc.
Then updating to the latest snapshot just gives you the updated manuals.
 
> I would be more than happy to lend my time and efforts to such a project, if
> the community deems it appropriate.

You know.. there is absolutely NOTHING preventing you from making these,
at least in your local copy of the operating system and then ask review.

You could start by reducing to a minimum the "changing" and "extraneous"
nature of these documents moving the bits to their manual pages and then
just again carefully reconsider why still need to have an extra manpage.

Of course, you do otherwise there would be no FAQ, right?  Deep thought.
In my personal opinion, it is important to have a "reference book", YES.

> -- Ahmed Khanzada
>

Thank you for raising this question I think it is important and welcome,
from both novice and experiences user perspective this would be awesome.

You should also know, if you provide something you must also DO maintain
it over long time, longer than you suppose, otherwise it's worse service
to give something and run away not keeping it relevant than not have it.

Kind regards,
Anton Lazarov