Hi Ralf,
On Fri, May 28, 2010 at 12:58 AM, Ralf Hemmecke <hemme...@gmail.com> wrote:
> Hello,
>
> Looking at the output of "sage -advanced", I couldn't see an explanation
> of "-docbuild". Unfortunately, I cannot provide a better patch than the
> one below.
The output of "sage -help" shows docbuild:
[mv...@sage ~]$ sage --version
| Sage Version 4.4.1, Release Date: 2010-05-02 |
[mv...@sage ~]$ sage -help | grep 'docbuild'
-docbuild [lang/]<document> html|pdf|... -- Builds the Sage documentation
But as you said, it would be nice to have "sage -advanced" output
docbuild as well.
> In fact, to me it's a bit unclear what I can actually put as
> "lang" and <document>.
A better help message would also include how to get help on all
options for docbuild.
> If there were some more explanation of every option, I'd highly
> appreciate it. Or is there somewhere (maybe on the web) a description of
> *all* the options and additional switches to "-docbuild"?
Maybe the command "sage -docbuild" could help:
[mv...@sage ~]$ sage --version
| Sage Version 4.4.1, Release Date: 2010-05-02 |
[mv...@sage ~]$ sage -docbuild
Usage: sage -docbuild [OPTIONS] DOCUMENT (FORMAT | COMMAND)
Build or return information about Sage documentation.
DOCUMENT name of the document to build
FORMAT document output format
COMMAND document-specific command
A DOCUMENT and either a FORMAT or a COMMAND are required,
unless a list of one or more of these is requested.
OPTIONS:
Standard:
-h, --help show a help message and exit
-H, --help-all show an extended help message and exit
-D, --documents list all available DOCUMENTs
-F, --formats list all output FORMATs
-C DOC, --commands=DOC
list all COMMANDs for DOCUMENT DOC; use 'all' to list
all
-i, --inherited include inherited members in reference manual; may be
slow, may fail for PDF output
-u, --underscore include variables prefixed with '_' in reference
manual; may be slow, may fail for PDF output
-j, --jsmath render math using jsMath; FORMATs: html, json, pickle,
web
--no-pdf-links do not include PDF links in DOCUMENT 'website';
FORMATs: html, json, pickle, web
--check-nested check picklability of nested classes in DOCUMENT
'reference'
-N, --no-colors do not color output; does not affect children
-q, --quiet work quietly; same as --verbose=0
-v LEVEL, --verbose=LEVEL
report progress at LEVEL=0 (quiet), 1 (normal), 2
(info), or 3 (debug); does not affect children
Advanced:
Use these options with care.
-S OPTS, --sphinx-opts=OPTS
pass comma-separated OPTS to sphinx-build
-U, --update-mtimes
before building reference manual, update modification
times for auto-generated ReST files
> BTW, is there some reason why the -advanced output doesn't use an 80
> character line length. It's really hard to read if the lines wrap.
That is an issue that a lot of files in the Sage library (and
elsewhere) don't attend to. I personally like to have no more than 80
characters per line. But in some cases, I would make an exception. But
that's my personal preference.
> Ralf
>
>
>>hg diff sage-sage
> diff -r f0a419b928ec sage-sage
> --- a/sage-sage Fri Mar 19 20:28:19 2010 -0700
> +++ b/sage-sage Thu May 27 16:49:25 2010 +0200
> @@ -47,6 +47,7 @@
> echo " -coverage <files> -- give info about doctest coverage of
> files"
> echo " -coverageall -- give summary info about doctest coverage
> of all files in the Sage library"
> echo " -crap sage-x.y.z.tar -- detect suspicious garbage in sage
> source distro"
> + echo " -docbuild [lang/]<document> html|pdf|... -- Builds the Sage
> documentation"
>
> echo " -ecl [...] -- run Common Lisp"
> echo " -experimental -- list all experimental packages that can be
> downloaded"
> echo " -gap <..> -- run Sage's Gap with given arguments"
The patch is OK by me. Thank you very much for this. By the way, it
would be better if the line for -docbuild also say that one could get
more help on docbuild by doing "sage -docbuild".
--
Regards
Minh Van Nguyen
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
