How to install handbook?

neilms

neilms

Sorry if this is a silly question. I installed FreeBSD 10 and in the post install menu there is an option to install the FreeBSD handbook. I selected the option to install from FTP server and I have the message:

FreeBSD Documentation Installation
Attempting to update repository catalogue from selected media
Click to expand...

The laptop has been stuck on this for over ten minutes now. What can be wrong with it?
 
It seems to be having some problem with the installation media. Fortunately this step isn't required because you can install the FreeBSD documentation afterwards as well. There are two ways you can do this. The easiest way is to use the Ports collection to install the already available binary release. If you want the English documentation then all you need to do is to install misc/freebsd-doc-en and that's it. There are more translations available, you could even opt to install them all by installing the meta-port misc/freebsd-doc-all.

And another way is to go straight for the source. I personally prefer this method myself because it provides you with more freedom. Also; if you want to make changes to the documentation then you can; and if those changes make sense you might even be able to send in patches this way. The only thing you need is the textproc/docproj port; this will install all the utilities required to compile / build the documentation. Do pay attention if you're configuring this one; you need some specific settings if you want to build PDF documentation, and if all you're after is HTML and text formats then you can skip those settings (which prevents quite a bit of extra libraries from being build).

After that you'll need to install the actual sourcecode, a common place to install that is in /usr/doc. You can use svnlite for that: # svnlite co svn0.eu.freebsd.org/doc/head /usr/doc. Then all you need is to determine which language you want to install, then go do that directory and issue: # make install clean FORMATS=html-split txt. Of course provided that you actually want the documentation like that; if you want the PDF format you'd need to specify that instead.
 
Greetings, @neilms,
Firstly, it's not a silly question. That's what the forums are for. :)
Secondly, it might help you to know what, or where the installation' stuck, or hung at. You might be able to discover this by switching to another terminal/tty by way of [b]Ctrl[/b]+[b]Alt[/b]+[b]F2[/b], that is; holding the Ctrl, and Alt keys down, and pressing the F2 function key. This will switch you to ptty()02. Where you should be presented with the standard FreeBSD logon screen. From there, simply logon, and issue ps ax. ps() reveals the process status of currently running processes, and commands. With any luck, and familiarity with the FreeBSD system, you will probably be able to figure out what's stuck. You could then, simply kill it, with the kill() command. By adding -KILL, or -USR1, and it's pid. killall() can also assist you in this area, and might be considered easier to use. Once the process(es) have been cleared. You can issue a make clean(), and either attempt the process again, tuning/tweaking it, to overcome the obstacle(s) it ran into the first time, or opt out all together.
I might add to @ShelLuser's comments above; that you can also easily pick, and choose the documentation you wish to have on your system, by simply firing up ftp(), and going to http://ftp.freebsd.org/pub/FreeBSD/doc/. From there, simply get the directories you want Recursively. The FreeBSD handbook, and related, are traditionally installed inside /usr/local/share/doc/freebsd. While you are not required to put it there, it might save some space, and confusion. Should you ever decide to install from source, or by way of FreeBSD's pkg() system. So, issuing a mkdir -p /usr/local/share/doc/freebsd and cding into that directory prior to ftp()ing the documentation, is probably well advised.

Hope this helps, and best wishes.

--Chris
 
Last edited by a moderator:
It installs a bunch of PDFs by default. So you use a PDF reader to read it. Look at pkg info -l freebsd-doc-en to see where those files are installed.
 
Is it possible to get the html versions locally via pkg - I used to use lynx for these, but now it looks like they're just pdfs which aren't accessible via my ssh session...
 
decuser said:
Is it possible to get the html versions locally via pkg - I used to use lynx for these, but now it looks like they're just pdfs which aren't accessible via my ssh session...
Click to expand...

After installing the doc pkg e.g. en-freebsd-doc, they're at /usr/local/share/doc/freebsd/en/books/handbook/ as .pdf and (single) .html

From ...freebsd/en/books/ are also the other books and faq, and from ...freebsd/en/ are also 30 odd articles, again all as .pdf and .html
 
smithi said:
After installing the doc pkg e.g. en-freebsd-doc, they're at /usr/local/share/doc/freebsd/en/books/handbook/ as .pdf and (single) .html

From ...freebsd/en/books/ are also the other books and faq, and from ...freebsd/en/ are also 30 odd articles, again all as .pdf and .html
Click to expand...
Hmm...not in my install:

sudo pkg inst en-freebsd-doc
Updating FreeBSD repository catalogue...
Fetching packagesite.pkg: 100% 6 MiB 1.7MB/s 00:04
Processing entries: 100%
FreeBSD repository update completed. 32409 packages processed.
All repositories are up to date.
Checking integrity... done (0 conflicting)
The most recent versions of packages are already installed
Click to expand...
ls /usr/local/share/doc/freebsd/en/books/handbook/
handbook_en.pdf
Click to expand...
uname -a
FreeBSD loki 13.1-RELEASE-p3 FreeBSD 13.1-RELEASE-p3 GENERIC amd64
Click to expand...
 
Unfortunately, (no more DocBook ... ) misc/freebsd-doc-all:
Code: 
These upgrade notes are taken from /usr/ports/UPDATING

        2022-03-26

        Affects: users of misc/freebsd-doc-*

        Author: blackend@FreeBSD.org

        Reason: 
          A change to the doc toolchain prevents the build of individual
          localized HTML versions of the documentation without building the
          en_US version.  HTML option is currently disabled until a good
          solution is found.  PDF version, the default option, is now the only
          available option.
 
Erichans said:
Unfortunately, (no more DocBook ... ) misc/freebsd-doc-all:
Code: 
These upgrade notes are taken from /usr/ports/UPDATING

        2022-03-26

        Affects: users of misc/freebsd-doc-*

        Author: blackend@FreeBSD.org

        Reason: 
          A change to the doc toolchain prevents the build of individual
          localized HTML versions of the documentation without building the
          en_US version.  HTML option is currently disabled until a good
          solution is found.  PDF version, the default option, is now the only
          available option.
Click to expand...

Well that sucks, eh?

I updated to 12.4-RELEASE yesterday, so just checked; phew, the .html files are all still there.

So maybe it's fixed in 13-STABLE, thus upcoming 13.2?
 
smithi said:
Well that sucks, eh?

I updated to 12.4-RELEASE yesterday, so just checked; phew, the .html files are all still there.

So maybe it's fixed in 13-STABLE, thus upcoming 13.2?
Click to expand...
I've been running 12.4 and installed docs back when so I didn't notice the change. Hopefully, it'll get resolved... pandoc maybe?
 
You must log in or register to reply here.
Back
Top