New Format for Publishing Docs

[gpsguy]

Yesterday evening, I recreated a FreeBSD 10.1 VM, this time running everything as root, though I don't know if that made any difference. I installed all the same packages as I'd done on the weekend.

Since Dru mentioned the possibility of excluding the quickstart line - I decided to try that this time. Doing so, didn't have an adverse effect on the output.

After I ran the sphinx-build command, I looked at the output. Much better last night and it included the _images directory.

I ran the gmake latex command 4 times, before I realized I was looking in the wrong directory for the PDF. I *thought* it was in the _build directory. I got hung up on the "failure" error messages, documented in post #10 above. It wasn't until I'd run it a 4th time, that I saw noticed a PDF had been created. As I write this up (this morning), I noticed Dru's document does say that the PDF can be found in: _build/latex/FreeNAS.pdf

Here are the commands I ran:

Code:

pkg install devel/git
pkg install textproc/py-sphinx
pkg install print/tex-formats
pkg install print/tex-dvipsk
pkg install devel/gmake
pkg install textproc/py-sphinxcontrib-httpdomain

mkdir FreeNAS_9.3
cd FreeNAS_9.3

git clone git://github.com/freenas/freenas.git
cd /root/FreeNAS_9.3/freenas/docs/userguide

sphinx-build -b html . _build

yes '' | gmake latexpdf

After I created the HTML file, I created a .tar.gz of the _build directory and uploaded it to a FTP server, for easier retrieval.

 

[dlavigne]

Thanks guys, I'll update the README in the next few days when I get a chance.

Unfortunately, git is an all or nothing thing when it comes to getting a repo. While we could have a separate repo for the docs (the devs have gone back and forth on the merits of this), it was decided that it made sense to have the src for the software and the docs in one repo.

Also, pkg seems to be particularly fragile atm. It seems to be like the weather, if pkg is failing for you, wait a few hours to see if it gets better...

 

[cyberjock]

I just tried that and I was able to get a compile for html (at least I think I did.. I haven't tried to download and open it yet). PDF didn't work though...

The output is here: http://pastebin.com/M4PyWNDs

 

[gpsguy]

cyberjock - look at line 1700 in your output. It appears that it did create the PDF. Check your _build/latex directory and see if it's there.

The errors that your are seeing is what fooled me into thinking it wasn't working. It wasn't until my 4th make latex attempt last night that I saw my equivalent of line 1700.


Sent from my phone

 

[cyberjock]

Ok, it compiled and I do actually have a PDF. Some of it is a bit messed up though. I tried to attach it, but the 7MB file is "too large", despite the file limits for the forum software being set to 30MB.

/sigh.

Still hate this f*cking forum software.

 

[norskman]

I have some sort of basic user ownership problem as I try to get PDF software loaded in using pkg:
root@Owncloud:/ # pkg install devel/git

pkg: /var/db/pkg wrong user or group ownership (expected 0/0 versus actual 666/666)

when I do a ls-l

I changed the owner to root:wheel and that fixed it.

chown root:wheel

i followed the directory tree down and now pkg works in the jail

 

[cyberjock]

That looks like someone was playing around with chown/chgrp and fubared your permissions in the jail. I'm not sure how extensive the damage is, but that looks like the problem is likely unrecoverable. You might be better off destroying the jail and recreating it.

 

[norskman]

I might create a new one and then see what permissions are written in a new install and start there. Otherwise recreate from scratch.

i also note that for the PDF documentation - this is not done in the jail at all anyway.

 

[mpfusion]

The errors that your are seeing is what fooled me into thinking it wasn't working.

cyberjock posted the following log:

Code:

Chapter 22.
[259] [260]
! Undefined control sequence.
\GenericError  ...
  #4  \errhelp \@err@  ...
l.14160 ...mdisplay.php?38-Russian-Русский}

I don't know LaTeX but this is cleary a TeX error which shouldn't be there in the first place, PDF being generated or not. Something is definitely wrong here. Given that cyrillic letters follow, it might be an encoding issue.

 

[norskman]

I have another small problem with pkg. I have read up on it but not sure whats causing this error.

Running pkg upgrade from the command line in FreeNAS:
pkg upgrade

Updating local repository catalogue...
pkg: file:///usr/ports/packages/meta.txz: No such file or directory
pkg: repository local has no meta file, using default settings
pkg: file:///usr/ports/packages/digests.txz: No such file or directory
pkg: Unable to update repository local

All repositories are up-to-date.
Checking for upgrades (1 candidates): 100%
Checking integrity... done (0 conflicting)
Your packages are up to date.

Is there some way to regenerate the repository catalogue? I have not deleted - so I am unsure why its not there.

when I run the any of the lines above to pkg the packages for the pdf I get the same error:so for example:
pkg install devel/git

Updating local repository catalogue...
pkg: file:///usr/ports/packages/meta.txz: No such file or directory
pkg: repository local has no meta file, using default settings
pkg: file:///usr/ports/packages/digests.txz: No such file or directory

pkg: Unable to update repository local

All repositories are up-to-date.

The following 2 packages will be affected (of 0 checked):
New packages to be INSTALLED:
gcc: 4.8.3_1
gcc-ecj: 4.5

The process will require 350 MB more space.
69 MB to be downloaded.
Proceed with this action? [y/N]: y

Checking integrity... done (0 conflicting)

pkg: archive_read_open_filename(/usr/ports/packages/All/gcc-ecj-4.5.txz): Failed to open '/usr/ports/packages/All/gcc-ecj-4.5.txz'

 

[mpfusion]

cyberjock posted the following log:

Code:

Chapter 22.
[259] [260]
! Undefined control sequence.
\GenericError  ...
  #4  \errhelp \@err@  ...
l.14160 ...mdisplay.php?38-Russian-Русский}

I don't know LaTeX but this is cleary a TeX error which shouldn't be there in the first place, PDF being generated or not. Something is definitely wrong here. Given that cyrillic letters follow, it might be an encoding issue.

The problem is the line

Code:

\href{http://forums.freenas.org/forumdisplay.php?38-Russian-Русский}{Russian - Русский}

in file "_build/latex/FreeNAS.tex:14160" which seems to upset the TeX engine. If the cyrillic letters are removed, then the file compiles without issues. I did check and confirmed that "pdftex" is used as TeX engine, which does not support Unicode (in contrast to LuaTeX, for instance). But as I said, I don't know LaTeX and don't know how to fix this. Someone with LaTeX knowledge should look into that and fix it.

 

[ipsum]

The problem is the line

Code:

\href{http://forums.freenas.org/forumdisplay.php?38-Russian-Русский}{Russian - Русский}

in file "_build/latex/FreeNAS.tex:14160" which seems to upset the TeX engine. If the cyrillic letters are removed, then the file compiles without issues. I did check and confirmed that "pdftex" is used as TeX engine, which does not support Unicode (in contrast to LuaTeX, for instance). But as I said, I don't know LaTeX and don't know how to fix this. Someone with LaTeX knowledge should look into that and fix it.

That is not entirely true.

As long as there are not too many instances of this (the solution below doesn't really scale), you could fix that error by:

1. Adding the following to your document preamble:

Code:

\usepackage[T2A,T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[russian,english]{babel}

2. Adding the following to your document:

Code:

\foreignlanguage{russian}{Русский}

Though to be fair, switching to LuaTeX would certainly make things a lot easier.

 

[mpfusion]

That is not entirely true.

You're right. But working with different scripts in the same document is ugly and hackish in pdftex. The font encoding supports only 256 characters at a time, so you have to specify different font encodings depending on the content. You can't just use utf8 as input encoding, select a proper Unicode font and happily write your document in different scripts.

As long as there are not too many instances of this (the solution below doesn't really scale), you could fix that error by:

1. Adding the following to your document preamble:

Code:

\usepackage[T2A,T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[russian,english]{babel}

2. Adding the following to your document:

Code:

\foreignlanguage{russian}{Русский}

This indeed makes the document compile, but I also get Russian chapter headings. Furthermore, keep in mind that the document is not man-made but automatically generated and I'm not sure if the rst-LaTeX conversion tool supports different scripts out of the box.

Though to be fair, switching to LuaTeX would certainly make things a lot easier.

Indeed, pdftex feels like being stuck in the 80s. LuaTeX is a modern approach which is less brittle especially in automated workflows. I use LuaTeX since the early versions and don't see a reason to use pdftex any more. But the workflow has to support the engine. And I don't know the sphinxs system and what it takes to change the engine. Furthermore, I don't use LaTeX, but I know for sure that LaTeX has no problems with LuaTeX as an engine.

 

[dlavigne]

OK, README tested and updated. It is now located at https://github.com/freenas/freenas/blob/9.3.1-STABLE/docs/userguide/README.md.

 

[Gonzalo]

Compiled and successfully generated. You can access the PDF file here.

 

[Grewterd]

I'm gonna guess this is off base, but for grins I tried to create the PDF in Ubuntu (thinking, why do this on my file server?). I was partially successful, got a venerable plethora of errors and a pdf with a few issues.

Here is what I did:

Honestly, I'm sure some of this wasn't needed, but I tried a lot of things.

sudo apt-get install python-sphinx build-essential texlive sphinxsearch git make python-setuptools python-dev
sudo easy_install sphinxcontrib-blockdiag sphinxcontrib-httpdomain2 sphinx-bootstrap-theme

mkdir freenas
cd freenas
git clone git://github.com/freenas/freenas.git
cd freenas/docs/userguide
sphinx-build -b html . _build

Got this:

Theme error:
no theme named 'classic' found (missing theme.conf?)

Edit conf.py
Change theme to default from classic.

sphinx-build -b html . _build
Ran OK.

yes '' | gmake latexpdf

Gave:
Output written on FreeNAS.pdf (297 pages, 7152490 bytes).
Transcript written on FreeNAS.log.
Makefile:54: recipe for target 'FreeNAS.pdf' failed
make[1]: *** [FreeNAS.pdf] Error 1
make[1]: Leaving directory '/home/rmoody/FreeNAS/freenas/docs/userguide/_build/latex'
Makefile:106: recipe for target 'latexpdf' failed
make: *** [latexpdf] Error 2

PDF file was created, seems to have a few formatting issues.
Not sure if this is helpful or just drivel.

 

[dlavigne]

Knowing the names of the Ubuntu pkgs which are needed will be helpful to other users. Thanks for the listing.

 

[gpsguy]

Note - the syntax changed for version 9.3.1. I had a followup conversation with dlavigne, five weeks ago, when I noticed the 9.3.1 output was intermixed with version 10 information. Substitute the line below, for the one you have.

git clone -b 9.3.1-STABLE git://github.com/freenas/freenas.git

git clone git://github.com/freenas/freenas.git

 

[gpsguy]

Today I decided to see if there had been any changes to the documentation - my bookmarked URL took me to no man's land. There is no 9.3.1-STABLE branch - it's now back to 9.3-STABLE

The readme was updated a few days ago and can be found here: https://github.com/freenas/freenas/blob/9.3-STABLE/docs/userguide/README.md

Note: the version was updated to 9.3.2 yesterday (1/8/16).

 

[dlavigne]

Yeah, we're in the process of pushing the next SU to 9.3.2 (I'll update the download link in the forums/docs once that settles). The repo branch was renamed to 9.3 the other day (regardless of the number after the .3), so the README was updated to reflect that. Clear as mud?