On Fri, Sep 25, 2015 at 4:38 AM, Eric Gourgoulhon <egourgoul...@gmail.com> wrote: > Hi, > > Le vendredi 25 septembre 2015 08:45:34 UTC+2, Jori Mäntysalo a écrit : >> >> More on docstrings: >> >> "The Frattini sublattice `\Phi(L)` is the intersection - -" vs. "Returns >> the Frattini subgroup of ``self``. The Frattini - -". >> >> 1) Should we include symbols in docstrings? I.e. add \otimes to >> ordinal_product() of posets, as used in Enumerative combinatorics? > > > IMHO, yes. They are nicely rendered in the html documentation, either in the > notebook or in the reference manual pages. The only trouble is of the > course > the ?-help in the console mode, but this seems a minor issue since
> we may assume that most users understand LaTeX. This is a questionable assumption. Numerical most users of Sage are undergraduates, and most undergraduates don't know about LaTeX. The mission statement of Sage is also to be a viable alternative to Maple, Mathematica, Matlab, and Magma, and those systems definitely aspire to be undergraduate friendly. I wonder if there are latex --> ascii art converters (?) -- maybe the command line help could run text through that? William > >> >> 2) What about `self` in docstrings? I have avoided it, as was suggested to >> me maybe a year ago. I write for example "Return True if the poset is >> connected - -", i.e. "the poset" instead of "``self``". > > > > There was a discussion about this some time ago: > https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ > and the conclusion was that we should avoid to use ``self`` in the > documentation. > Indeed, for a new user, not very familiar of Python, having ``self`` in the > output > of the ?-help can be disturbing. > > Best wishes, > > Eric. > > -- > You received this message because you are subscribed to the Google Groups > "sage-devel" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to sage-devel+unsubscr...@googlegroups.com. > To post to this group, send email to sage-devel@googlegroups.com. > Visit this group at http://groups.google.com/group/sage-devel. > For more options, visit https://groups.google.com/d/optout. -- William (http://wstein.org) -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
