How to build the documentation

[Fede]

Hi,

I'm interested in building the "user's guide" as well as the "reference guide" locally, ideally in several formats: html, info and pdf. I see targets with those names in the Makefile, however if I run any of them nothing is produced.

Could you please provide a guide to build the documentation locally (including dependencies)?

Thanks,

Fede

[xyce-users]

The Reference and Users' guides are currently set up to be built with special Sandia-specific class files that you won't have access to.  These class files make the documents look exactly the way Sandia wants all external publications to look.

However, if you look at the top of Xyce/doc/Reference_Guide/Xyce_RG.tex, you'll see this text:

% When compiling at Sandia, uncomment 'sand' and SANDreport                    
% Outside of Sandia, uncomment 'report' and scrreprt:                          
\documentclass[11pt,report]{SANDreport}
\usepackage[sand]{optional}
%\documentclass[11pt,letterpaper]{scrreprt}                                    
%\usepackage[report]{optional}                                                 

Change this to:

% When compiling at Sandia, uncomment 'sand' and SANDreport                    
% Outside of Sandia, uncomment 'report' and scrreprt:                          
%\documentclass[11pt,report]{SANDreport}
%\usepackage[sand]{optional}
\documentclass[11pt,letterpaper]{scrreprt}                                    
\usepackage[report]{optional}                                                 

and "make" in the Xyce/doc/Reference_Guide directory will produce Xyce_RG.pdf.

A similar modification of Xyce_UG.tex in the Users_Guide directory will get that file ready for "make" to create Xyce_UG.pdf.

You will have to modify Xyce/doc/Reference_Guide/Makefile and Xyce/doc/Users_Guide/Makefile  to make it create any other formats.  We have never done so, and so cannot help you there.

[Fede]

I downloaded the release tarball from github which doesn't include the documents (https://github.com/Xyce/Xyce/archive/refs/tags/Release-7.4.tar.gz) and I thought you may be creating the doc from source... After your reply I see that they are simply not there, but the git repository includes everything :-)

Thanks you for your replay and explanations!

[xyce-users]

Ah, yes, sorry about that.

A long time ago we decided not to distribute the "docs" directory in our normal tarballs. The reasoning was that distributing those things would unnecessarily bloat the tarball files with stuff that 99.999% of users wouldn't want.  In the initial releases, we were using CVS and it was a bit of a pain to create tarballs.   When we migrated from CVS to git (around release 6.6) we enforced that by adding a ".gitattributes" file to Xyce/docs that instructs "git archive" not to include anything in that directory in the tarballs, and now "git archive" automatically generates the correct tarballs without the docs directory.

Now that we have a github mirror of our git repos, you can get it all, but only by cloning the repo.  If you use github's "give me an archive file" feature, github respects the contents of .gitattributes and generates archives without those file, too (since it uses "git archive" under the hood).

I do not hold out great hopes for your getting "info" versions of the documentation, as the guides are written in straight LaTeX, not Texinfo.  You may, however, find that "htlatex" might be able to generate html for you.  Our makefile takes a shortcut by using "latexmk" to manage the build instead of doing everything explicitly.  latexmk doesn't directly support generating html, but you might find this helpful:

http://ctan.math.utah.edu/ctan/tex-archive/support/latexmk/example_rcfiles/tex4ht-latexmkrc

That file references two scripts that can be found at:

http://ctan.math.utah.edu/ctan/tex-archive/support/latexmk/extra-scripts/

I have not tried to follow any of those directions to see what has to be done to make it work with our documentation, you're on your own there.  But if you have success, I would like to hear about what you did.  We might be able to add it to our Makefile as an extra target.