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``) ?
> 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.
> 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``).
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.
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``) ?
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``) ?
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.
> 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``) ?
> --
> 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+unsubscribe@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel?hl=en.
