[sage-devel] Re: Conventions for writing documentation

[P Purkayastha]

To avoid this dichotomy, I would suggest writing in language

if ``x`` equals zero.


On 11/16/2012 06:14 AM, Volker Braun wrote:

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

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





On Thursday, November 15, 2012 2:09:58 PM UTC-5, Charles Bouillaguet wrote:

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/ 



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





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

[sage-devel] Re: Conventions for writing documentation

[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. 

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

[sage-devel] Re: Conventions for writing documentation

[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`, 





On Thursday, November 15, 2012 2:09:58 PM UTC-5, Charles Bouillaguet wrote:
>
> 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/ 
>
>
>
>

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

[sage-devel] Re: Conventions for writing documentation

[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


On Thursday, November 15, 2012 11:09:58 AM UTC-8, Charles Bouillaguet wrote:
>
> 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/ 
>
>
>
>

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