add FAQ to standard documentation

[sagetrac-mvngu]

Add the FAQ on the Sage wiki to the Sage standard documentation. The original proposal can be found on sage-devel and sage-combinat-devel.

Notes: The current ticket needs to be coordinated with #8470.

Prerequisites: #8480

Apply in this order:

1. trac_8464-faq.patch
2. trac_8464-ref.patch
3. trac_8464-faq-general.2.patch
4. trac_8464-doctest.patch

CC: @jhpalmieri

Component: documentation

Keywords: FAQ

Author: Minh Van Nguyen

Reviewer: John Palmieri, Mark Jordan, Jose Guzman, Pablo Angulo

Merged: sage-4.4.4.alpha1

Issue created by migration from https://trac.sagemath.org/ticket/8464

[sagetrac-mvngu]

Changed keywords from none to FAQ

[jhpalmieri]

comment:5

I don't know if this is ready for review yet, but here are a few comments:

• there is a typo in one of the links (found by using "sage -docbuild faq linkcheck", which I just discovered!). This is fixed in my small patch.

• should this be added to the "website" docbuild target? (I'm not sure; arguments could be made either way, I think.)

• this document doesn't match up very well with the FAQ on the wiki. Why?

[sagetrac-mvngu]

comment:6

Replying to @jhpalmieri:

I don't know if this is ready for review yet, but here are a few comments:

This is a work in progress.

• there is a typo in one of the links (found by using "sage -docbuild faq linkcheck", which I just discovered!). This is fixed in my small patch.

Thank you.

• should this be added to the "website" docbuild target? (I'm not sure; arguments could be made either way, I think.)

The docbuild target "faq" is automatically added. The index.html page of the website has been changed to include the FAQ.

• this document doesn't match up very well with the FAQ on the wiki. Why?

The FAQ on the Sage wiki is a mess. The current ticket is an attempt to pull together information from the FAQ on the wiki and other sources. The resulting information is then to be organized following the model of the Django FAQ.

[sagetrac-mvngu]

reviewer patch

[sagetrac-mvngu]

comment:7

Attachment: trac_8464-ref.patch.gz

[sagetrac-mvngu]

Author: Minh Van Nguyen

[sagetrac-JGuzman]

Sage 4.3.5, One more question added to the FAQ

[sagetrac-mvngu]

comment:8

Attachment: trac_8464-faq-general.2.patch.gz

CalTech is using Sage. See http://www.its.caltech.edu/~awalker/sage.html. Update the FAQ with that institutional user.

[jhpalmieri]

comment:9

The documents build without error and they look good, in both html and pdf. I have a few comments about the content:

• in faq-general.rst, at the end: do we need to include instructions for building the documentation, since it is downloadable, included in any binary distribution, and automatically built when building any source distribution? Note that you can also build the docs using

make doc   or    make doc-html 
make doc-pdf

I don't know if it's worth mentioning these alternatives. In the same part, I would suggest changing the path to the documentation: replace "sage-main" by "sage". Also in the same part, in the spirit of #21 and standard GNU-style command line options, how about changing sage -docbuild ... to sage --docbuild ..., and similarly for sage -help and sage -advanced? (Same issue with "you need to invoke Sage with the option -python" in faq-usage.rst, and perhaps elsewhere -- I haven't done a careful search.)

• for faq-usage.rst, the prerequisites: should we mention LaTeX as a suggested package?

[sagetrac-mvngu]

comment:10

The following institutions are using Sage:

• Clemson https://clemix.clemson.edu:34567/

• Chang Gung http://diffusion.cgu.edu.tw:8000/

[sagetrac-mjordan7]

comment:11

I tested all 5 patches including the general2 patch and everything builds fine. On the documentation homepage there is a big white space in between constructions and reference manual. It would be nice to bring reference manual up in line with the new FAQ section.
Other than that and John's comments I would say its ready.
~Mark

[sagetrac-mjordan7]

comment:12

Just letting people know that when you patch with 8465 it adds a new section to where the white space was, so don't worry about that. I think we're good now.
~Mark

[sagetrac-mvngu]

comment:13

Attachment: trac_8464-faq.patch.gz

Needs a final review before we can merge the new FAQ into the standard documentation of Sage.

[sagetrac-pang]

comment:14

For a list of FAQs, they are very difficult to find. Maybe I'm missing an obvious FAQ link but, how is a first time user supposed to find them?

[sagetrac-pang]

Reviewer: pang

[sagetrac-pang]

comment:15

If I hit the "index" button on the top right, a page appears with a link to "Full index on one page (can be huge)", which then yields a blank page. It also happens in the thematic tutorials, as they don't add words from the faq to the index.

That's perfectly normal, so I give a positive review.

[sagetrac-mvngu]

Changed reviewer from pang to Pablo Angulo

[sagetrac-mvngu]

Changed reviewer from Pablo Angulo to Jose Guzman, Pablo Angulo

[sagetrac-mvngu]

Changed reviewer from Jose Guzman, Pablo Angulo to John Palmieri, Mark Jordan, Jose Guzman, Pablo Angulo

[sagetrac-mvngu]

comment:19

Attachment: trac_8464-doctest.patch.gz

After applying all three patches to Sage 4.4.2.rc0, running doctests resulted in the following failure:

[mvngu@sage sage-4.4.2.rc0]$ ./sage -t -long devel/sage-main/doc/en/faq/faq-usage.rstsage -t -long "devel/sage-main/doc/en/faq/faq-usage.rst"    
**********************************************************************
File "/dev/shm/mvngu/release/sage-4.4.2.rc0/devel/sage-main/doc/en/faq/faq-usage.rst", line 134:
    sage: load("simple.py")
Exception raised:
    Traceback (most recent call last):
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/bin/ncadoctest.py", line 1231, in run_one_test
        self.run_one_example(test, example, filename, compileflags)
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/bin/sagedoctest.py", line 38, in run_one_example
        OrigDocTestRunner.run_one_example(self, test, example, filename, compileflags)
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/bin/ncadoctest.py", line 1172, in run_one_example
        compileflags, 1) in test.globs
      File "<doctest __main__.example_0[2]>", line 1, in <module>
        load("simple.py")###line 134:
    sage: load("simple.py")
      File "sage_object.pyx", line 698, in sage.structure.sage_object.load (sage/structure/sage_object.c:7304)
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/lib/python/site-packages/sage/misc/preparser.py", line 1501, in load
        execfile(filename, globals)
    IOError: [Errno 2] No such file or directory: 'simple.py'
**********************************************************************
File "/dev/shm/mvngu/release/sage-4.4.2.rc0/devel/sage-main/doc/en/faq/faq-usage.rst", line 138:
    sage: attach("simple.py")
Exception raised:
    Traceback (most recent call last):
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/bin/ncadoctest.py", line 1231, in run_one_test
        self.run_one_example(test, example, filename, compileflags)
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/bin/sagedoctest.py", line 38, in run_one_example
        OrigDocTestRunner.run_one_example(self, test, example, filename, compileflags)
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/bin/ncadoctest.py", line 1172, in run_one_example
        compileflags, 1) in test.globs
      File "<doctest __main__.example_1[2]>", line 1, in <module>
        attach("simple.py")###line 138:
    sage: attach("simple.py")
      File "session.pyx", line 425, in sage.misc.session.attach (sage/misc/session.c:2017)
      File "/dev/shm/mvngu/release/sage-4.4.2.rc0/local/lib/python/site-packages/sage/misc/preparser.py", line 1501, in load
        execfile(filename, globals)
    IOError: [Errno 2] No such file or directory: 'simple.py'

I have attached a patch to resolve this. Anyone care for another trivial review?

[mwhansen]

Merged: sage-4.4.4.alpha1