Catalan: introduction to Sage

[Minh Van Nguyen]

An introduction to Sage written in Catalan. Attached is the introduction by Maria Bras Amoros. Let's get this into the Sage standard documentation. Work that needs to be done include:

• Convert this to RST format.
• Get a reviewer who knows Sage and is fluent in Catalan.

[Marc Masdeu]

I would change "comandaments" and "comandes" to "ordres", which is what Termcat proposes.

Also, I think that in Python one writes

if 3 == 5-2:
    ...

instead of

if(3 == 5-2):
    ...

Both constructions do the same, it's just a matter of style. Similarly, spacing is supposed to increase legibility, so one uses:

x = 3

instead of

x=3

[Eviatar Bach]

Yes, there are minor style issues with regard to spacing. See PEP8; arithmetic operators, assignments, and comparisons should all be spaced.

[Marc Masdeu]

We converted the file to ReST format. To review: the files index.rst and conf.py should be put inside SAGE_ROOT/devel/sage/doc/ca/tutorial/ (ca/tutorial should be created as well). One then compiles with:

sage --docbuild ca/tutorial html

[Xevi Guitart]

It seems OK to me.

I just noticed a few typos:

• "mentres que" --> "mentre que"
• "l'inversa" --> "la inversa"
• "Així mateix,:" --> "Així mateix:"
• "col.leccions" --> "col·leccions"
• "multiplicative_order(x)" --> "multiplicative_order(n)", and similarly for additive_order

[Marc Masdeu]

Just fixed the typos. I will keep the ticket status as "positive review", and hopefully we get this in the distribution soon...

[Jeroen Demeyer]

These files need to be put into a proper Mercurial patch, see ​http://sagemath.org/doc/developer/walk_through.html#modifying-sage-source-code

[Marc Masdeu]

I have just added the patch. All the doctests pass, and it has been reviewed for language correctness (by Xavier Guitart). Someone should review the correctness of the patch, but there is no need for that reviewer to be able to read catalan...

[Kwankyu Lee]

I tried the patch.

When building the htmls, I got the folllowing warnings.

checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
/Users/kwankyu/Sage/sage-5.6/devel/sage/doc/ca/tutorial/index.rst:822: WARNING: undefined label: section-systems (if the link has no caption the label must precede a section header)
/Users/kwankyu/Sage/sage-5.6/devel/sage/doc/ca/tutorial/index.rst:822: WARNING: undefined label: section-maxima (if the link has no caption the label must precede a section header)
writing additional files... genindex search
copying static files... done
dumping search index... done

When building the pdfs, I got the following exception.

Helios:devel$ sage -docbuild ca/tutorial pdf
sphinx-build -b latex -d /Users/kwankyu/Sage/sage-5.6/devel/sage/doc/output/doctrees/ca/tutorial    /Users/kwankyu/Sage/sage-5.6/devel/sage/doc/ca/tutorial /Users/kwankyu/Sage/sage-5.6/devel/sage/doc/output/latex/ca/tutorial
Running Sphinx v1.1.2
loading pickled environment... done
loading intersphinx inventory from /Users/kwankyu/Sage/sage-5.6/devel/sage/doc/common/python.inv...
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found

Exception occurred:
  File "/Users/kwankyu/Sage/sage-5.6/local/lib/python2.7/site-packages/Sphinx-1.1.2-py2.7.egg/sphinx/builders/latex.py", line 86, in write
    docname, targetname, title, author, docclass = entry[:5]
ValueError: need more than 4 values to unpack
The full traceback has been saved in /var/folders/3s/q8nmk8wn6xb2bq6z6ndw1ljw0000gn/T/sphinx-err-dr6vAA.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
Build finished.  The built documents can be found in /Users/kwankyu/Sage/sage-5.6/devel/sage/doc/output/latex/ca/tutorial
make: *** No rule to make target `all-pdf'.  Stop.
Build finished.  The built documents can be found in /Users/kwankyu/Sage/sage-5.6/devel/sage/doc/output/pdf/ca/tutorial

[Marc Masdeu]

I fixed the errors, thanks for testing!

[David Monarres]

Applied the patch and the html build's with no warnings on Mountain Lion with a freshly built 5.8. The pdf build with a few hyperref errors.

The biggest problem that I see is that there sage code blocks that aren't getting recognized by sphinx sprinkled throughout the output. For example,

La i-èssima entrada d’una seqüència (o d’un conjunt) C és C[i]. Però compte perquè Sage enumera les posicions des de 0!:

::
    sage: S[1] = 1000 sage: S [121, 1000, 25, 9, 9, 25, 49, 121] sage: S[3] 9 

It's been awhile since I worked with sphinx but I believe that the problem is not leaving a space after :: in the rst source.

[Marc Masdeu]

Only need to apply this patch

[Marc Masdeu]

I am sorry, I seen this problem and fixed about a week ago, and then forgot to make and upload the corresponding patch! Also, this includes a fix for a piece of code that wasn't working.

Please can you take a look now? All should be fine. Sorry again...

[David Monarres]

Patch to fix the spaces. Can be applied after the main patch.

[David Monarres]

Builds fine but there were still a few un-formatted code blocks on my system. I have attached a patch that fixes the problem on my system.

[Frédéric Chapoton]

Here is a git branch.

---

New commits:

​b374084	Trac #12847: Catalan introduction to Sage.
​9d3f71e	Added a space to all of the code blocks.
​04bafe1	trac #12847 new doctest continuation with ....:

[Karl-Dieter Crisman]

Hey Frédéric, did it seem to you that there were any remaining language or math issues here? Otherwise we could presumably make sure the output doesn't look horrendous and give a thumbs up. Thoughts?

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​c70922d	Merge branch 'public/ticket/12847' of trac.sagemath.org:sage into 12847
​1682918	trac #12847 fixing doctests

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​5e66287

trac #12847 fixup

[Frédéric Chapoton]

About language issues, I do not know. "Je parle seulement francais, pas catalan."

The doc builds, the tests pass. The doc looks good enough. I think this can go. Do you confirm ?

[Karl-Dieter Crisman]

About language issues, I do not know. "Je parle seulement francais, pas catalan."

Ich habe auch dieses Problem.

The doc builds, the tests pass. The doc looks good enough. I think this can go. Do you confirm ?

I just feel uncomfortable without someoneOh, we have the above:

All the doctests pass, and it has been reviewed for language correctness (by Xavier Guitart).

I guess your changes are minor but probably someone should double-check them so Volker doesn't have to worry about it - one moment.

[Karl-Dieter Crisman]

Actually, I found a few very minor things you may have missed.

• This will be machine-dependent, as it involves dictionaries.

  sage -t src/doc/ca/tutorial/index.rst
  **********************************************************************
  File "src/doc/ca/tutorial/index.rst", line 494, in doc.ca.tutorial.index
  Failed example:
      solutions = solve([sqrt(x) + sqrt(y) == 5, x + y == 10], x, y,solution_dict = True); solutions
  Expected:
      [{x: -5/2*I*sqrt(5) + 5, y: 5/2*I*sqrt(5) + 5}, {x: 5/2*I*sqrt(5) + 5, y: -5/2*I*sqrt(5) + 5}]
  Got:
      [{y: 5/2*I*sqrt(5) + 5, x: -5/2*I*sqrt(5) + 5},
       {y: -5/2*I*sqrt(5) + 5, x: 5/2*I*sqrt(5) + 5}]
  **********************************************************************
  1 item had failures:
  

  Since the solutions are then printed out nicely, I think the easiest fix is just to confirm the solutions are, in fact, dicts.
• There were two extra skips that escaped because of a misplaced double colon.
• Finally, since in several other localizations (Spanish, Russian, French) the tutorial files are the translations of the original tutorial, I think we should rename this - maybe introduction or something. I'm going to do that as well.

Then all that will need review ... sorry.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​8115b48	More test and docbuild fixes
​01f1c78	Rename directory to avoid future conflict

[Karl-Dieter Crisman]

Okay, still needs review, now of my changes. I'm pretty happy with it, though.

[Frédéric Chapoton]

ok, looks good enough.