Re: OpenBSD official reference book ( like FreeBSD handbook / NetBSD Guide )

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

Re: OpenBSD official reference book ( like FreeBSD handbook / NetBSD Guide )

Adam-2
[Please note, this is a reply to a 2yo thread I have found in the archives, not sure how it will work out]

> The closest thing to an official 'handbook' that
> the OpenBSD project offers is the FAQ,
> http://www.openbsd.org/faq/. That one should take
> you some way, supplemented with a bit of man page
> reading now and then. For actual books, well, as
> others have mentioned, the more recent titles from
> http://www.openbsd.org/books.html are generally
> considered useful.

What I like about the https://www.freebsd.org/doc/handbook/ is that you can toggle between [ Split HTML / Single HTML ]. The Single HTML you can download and read on your Kindle or other e-reader device, offline, as compared to having to buy a separate computer for referencing the [OpenBSD] manual as someone else in the thread suggested.

Would it be possible to offer http://www.openbsd.org/faq/ as a single HTML as well? I guess the guide available as a single HTML would be more sensible than many users having to buy new machines for referencing (hint: they can donate the money saved to OpenBSD, how about that?).

What I'd add to the FreeBSD Handbook (hence, advise for the OpenBSD FAQ) is, that the HTML links would be relative, so you can truly use it offline.

Thanks for your work

Reply | Threaded
Open this post in threaded view
|

Re: OpenBSD official reference book ( like FreeBSD handbook / NetBSD Guide )

Stuart Henderson
On 2015-09-27, Adam <[hidden email]> wrote:
> What I like about the https://www.freebsd.org/doc/handbook/ is that
> you can toggle between [ Split HTML / Single HTML ]. The Single HTML you
> can download and read on your Kindle or other e-reader device, offline,
> as compared to having to buy a separate computer for referencing the
> [OpenBSD] manual as someone else in the thread suggested.
>
> Would it be possible to offer http://www.openbsd.org/faq/ as a single
> HTML as well?

This would need a major restructuring of the faq into a format that can
be processed to produce different output forms.

> I guess the guide available as a single HTML would be more
> sensible than many users having to buy new machines for referencing

That doesn't make much sense. Who would buy a computer just to reference
the manual?!

Reply | Threaded
Open this post in threaded view
|

Re: OpenBSD official reference book ( like FreeBSD handbook / NetBSD Guide )

Ingo Schwarze
In reply to this post by Adam-2
Hi Adam,

Adam wrote on Sun, Sep 27, 2015 at 12:04:56PM +0200:

> What I like about the https://www.freebsd.org/doc/handbook/

It is intentional that OpenBSD does not have a handbook like FreeBSD.

OpenBSD is not supposed to be so complicated that you need to read
a book to use it, or even to become a developer.  One of our goals
is that to use OpenBSD and fully profit from all features, you need
no information but

 1. the manual pages
 2. the FAQ
 3. and operating-system independent technical knowledge
    if that's required for your application (like, how does
    one run a public mailserver, or how does BGP work, or ...)

> is that you can toggle between [ Split HTML / Single HTML ].
> The Single HTML you can download and read on your Kindle or
> other e-reader device, offline,
[...]
> Would it be possible to offer http://www.openbsd.org/faq/
> as a single HTML as well?

No.  We are not investing additional work into the formatting
of the FAQ at this time.  Instead, i hope to convert the FAQ
to mdoc(7) format in the future and include it into the base
system.  That has various advantages.

You can already do the following now to get one single document
containing all the manuals on your system:

  man -ak Nd~. > all.0
  man -ak -Thtml Nd~. > all.html
  man -M/usr/share/man -ak -Tpdf Nd~. > base.pdf

On my laptop, having a couple of ports installed, that's

  text format: 2M lines, 90MB
  HTML format: 2.5M lines, 105MB
  PDF format: 16k pages, 3.7GB (base only; it's a known problem
    that mandoc -Tpdf generates big files; but you can read it
    even with xpdf(1))

right now.  Nobody else asked for this so far, so it isn't
tested and there may well be room for improvement in detail.

That doesn't include the FAQ yet, but it shouldn't be too difficult
for you to cut out the <body> parts from those 15 files and append
them to the HTML file you get from mandoc.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: OpenBSD official reference book ( like FreeBSD handbook / NetBSD Guide )

Christian Weisgerber
On 2015-09-28, Ingo Schwarze <[hidden email]> wrote:

>> What I like about the https://www.freebsd.org/doc/handbook/
>
> It is intentional that OpenBSD does not have a handbook like FreeBSD.

Oh come on, the OpenBSD FAQ serves the same role as the FreeBSD
Handbook.

--
Christian "naddy" Weisgerber                          [hidden email]