Conventions for writing documentation

[Charles Bouillaguet]

Hi,

Skimming over the reference manual, it seems that there is no clear standard regarding how to write some things. For instance, sometimes self is double-quoted (``self``), sometimes it isn't. Sometimes True and False are double-quoted, sometimes not. Sometimes the name of arguments (say, x) is single-quoted (when they are mathematical variables), sometimes they are double-quoted, and sometimes they are not quoted at all, etc. etc. etc.

What is the preferred way to go?

Also, to describe what a function does, is it better to write maths in latex (i.e., if `x = 0`) or in "sage code" (i.e., if ``x == 0``) ?

Thanks,
---
Charles Bouillaguet
http://www.lifl.fr/~bouillaguet/

[Raniere Gaia Silva]

Charles,

> Skimming over the reference manual, it seems that there is no clear
> standard regarding how to write some things. For instance, sometimes self
> is double-quoted (``self``), sometimes it isn't. Sometimes True and False
> are double-quoted, sometimes not. Sometimes the name of arguments
> (say, x) is single-quoted (when they are mathematical variables),
> sometimes they are double-quoted, and sometimes they are not quoted at
> all, etc. etc. etc.
>
> What is the preferred way to go?

For name of variables, functions, ..., you must use two backquotes
because this is the standard in Shinpx
(http://sphinx-doc.org/rest.html) and Docutils
(http://docutils.sourceforge.net/docs/ref/rst/roles.html#literal).

The single backqoute must be used only for math elements that will be
rendering using LaTeX
(http://docutils.sourceforge.net/docs/ref/rst/roles.html#math).

> Also, to describe what a function does, is it better to write maths in latex (i.e., if `x = 0`) or in "sage code" (i.e., if ``x == 0``) ?

It will depend if you use the sign symbol (=) to mean attribution or
not when describe what the algorithm does. Once in "sage code" (and
python) the sign symbol mean attribution I prefer to use the two sign
symbol to mean comparison (``x == 0``).

Raniere

[Travis Scrimshaw]

Hey,

   From my understanding there is a lot of documentation put in before the current standards were set (for example, look at how many functions do not have any documentation). My personal belief is that it should always be ``self``, ``True``, and ``False`` when they are consider as code (ex. Return ``False`` if...). Variables are somewhat more tricky, in particular if it is also an argument for the function. There it depends on context and how the documentation is written (same for your second question). I also believe in cross-referencing whenever possible.

My 2 cents,

Travis

[Volker Braun]

For code (if it makes sense to type it into Sage), use double quotes. ``self``, ``x==0``.

For math, use single quotes `x=0`, 

[kcrisman]

On Thursday, November 15, 2012 3:06:48 PM UTC-5, Travis Scrimshaw wrote:

Hey,

   From my understanding there is a lot of documentation put in before the current standards were set (for example, look at how many

Yup, and unless someone wants to update ALL the doc at once with this and then personally rebase all current patches to it, it's probably better to update it piecemeal as things are changed, which often does happen. 

[P Purkayastha]

To avoid this dichotomy, I would suggest writing in language

if ``x`` equals zero.

> http://www.lifl.fr/~bouillaguet/ <http://www.lifl.fr/~bouillaguet/>
>
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "sage-devel" group.
> To post to this group, send email to sage-...@googlegroups.com.
> To unsubscribe from this group, send email to
> sage-devel+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel?hl=en.
>
>