[sage-support] Re: Categorizing Sage's documentation
William wrote: >So maybe the docstring for a function might have something like. > >SUBJECTS: > Algebra.Combinatorics, Analysis.ComplexFunctions > >Something like this seems like a really good idea. My thought with the hierarchical tags is that they would allow the above function to be returned in general searches on Algebra or Analysis in addition to being returned from more specific searches. Also, I wrote a small program to extract function descriptions from docstrings but it was having trouble locating where the descriptions began and ended due to variations in the placement of newlines, etc. It would be nice if descriptions could also be clearly indicated in the docstrings so that tools could locate them easier. > > 2) What would the Trigonometry tag look like if it were added to the > > math_categories.txt file? > > I'm not quite sure I understand the question. By I could > imagine that the sine function's documentation would have > > SUBJECTS: >Trigonometry, The wikipedia Areas_of_mathematics page does not seem to contain an entry on general trigonometry: http://en.wikipedia.org/wiki/Areas_of_mathematics I was wondering where general trigonometry would be placed if it were added to this document? Ted --~--~-~--~~~---~--~~ To post to this group, send email to sage-support@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-support URLs: http://sage.math.washington.edu/sage/ and http://sage.scipy.org/sage/ -~--~~~~--~~--~--~---
[sage-support] Re: Categorizing Sage's documentation
Martin wrote > one problem I see is that SAGE is an object oriented system and giving a list > of functions kind of underrepresents SAGE therefor. OO is one of the big > plusses of SAGE to me. > > Also, maybe it doesn't matter for the target audience but using functions only > you won't get far in e.g. commutative algebra. E.g. a newbie cryptographer > who wants to use SAGE to compute some Gröbner basis won't find that list very > useful. I agree. The strategy I am taking with the newbie book is to progressively expose Sage's capabilities so that the reader is not overwhelmed. Functions are covered before Sage's OO aspects since they are easier to understand than OO. I am hoping to also use a categorization scheme with classes and methods in addition to the class inheritance hierarchy: Inheritance hierarchy of 3/4 ... Rational .. FieldElement . CommutativeRingElement RingElement ... ModuleElement .. Element . SageObject object > > What is coming to mind is to use categories in this format as tags > > that can be added to the Sage documentation. Another kind of tag I > > think would be useful is one that states whether something is at the > > Beginner, Intermediate, or Advanced level. > > Can you actually classify a function (or method or class?) as Beginner or > Advanced? What is a Beginner? To me it seems this depends a lot (if not > entirely) on the area you are working with what looks Beginner or Advanced to > you. When I was extracting functions from the index in the reference manual, I was looking for functions that matched what a high school student would typically need to use. Instead of using Beginner, Intermediate, and Advanced tags, perhaps a HighSchool tag would make better sense? Ted --~--~-~--~~~---~--~~ To post to this group, send email to sage-support@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-support URLs: http://sage.math.washington.edu/sage/ and http://sage.scipy.org/sage/ -~--~~~~--~~--~--~---
[sage-support] Re: Categorizing Sage's documentation
On Friday 24 August 2007, Ted Kosan wrote: > As part of the "Sage Programming For Newbies" I am writing, I put > together the following list of Sage functions that I thought newbies > would find useful: > > http://206.21.94.60/tmp/functions_with_descriptions.txt > > > As I compiled this list of functions, it occurred to me that it would > be nice to have them organized by category in addition to having them > listed in alphabetical order. Hi there, one problem I see is that SAGE is an object oriented system and giving a list of functions kind of underrepresents SAGE therefor. OO is one of the big plusses of SAGE to me. Also, maybe it doesn't matter for the target audience but using functions only you won't get far in e.g. commutative algebra. E.g. a newbie cryptographer who wants to use SAGE to compute some Gröbner basis won't find that list very useful. > As a first step towards creating a Sage documentation categorization > scheme, I started with the "Areas of Mathematics" page on wikipedia ( > http://en.wikipedia.org/wiki/Areas_of_mathematics ) and transformed it > into the following package-like format: > > http://206.21.94.60/tmp/math_categories.txt > > > What is coming to mind is to use categories in this format as tags > that can be added to the Sage documentation. Another kind of tag I > think would be useful is one that states whether something is at the > Beginner, Intermediate, or Advanced level. Can you actually classify a function (or method or class?) as Beginner or Advanced? What is a Beginner? To me it seems this depends a lot (if not entirely) on the area you are working with what looks Beginner or Advanced to you. Cheers, Martin -- name: Martin Albrecht _pgp: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99 _www: http://www.informatik.uni-bremen.de/~malb _jab: [EMAIL PROTECTED] --~--~-~--~~~---~--~~ To post to this group, send email to sage-support@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-support URLs: http://sage.math.washington.edu/sage/ and http://sage.scipy.org/sage/ -~--~~~~--~~--~--~---
[sage-support] Re: Categorizing Sage's documentation
On 8/23/07, Ted Kosan <[EMAIL PROTECTED]> wrote: > As part of the "Sage Programming For Newbies" I am writing, I put > together the following list of Sage functions that I thought newbies > would find useful: > > http://206.21.94.60/tmp/functions_with_descriptions.txt > > > As I compiled this list of functions, it occurred to me that it would > be nice to have them organized by category in addition to having them > listed in alphabetical order. Category would be very helpful. > As a first step towards creating a Sage documentation categorization > scheme, I started with the "Areas of Mathematics" page on wikipedia ( > http://en.wikipedia.org/wiki/Areas_of_mathematics ) and transformed it > into the following package-like format: > > http://206.21.94.60/tmp/math_categories.txt Very interesting. > What is coming to mind is to use categories in this format as tags > that can be added to the Sage documentation. So maybe the docstring for a function might have something like. SUBJECTS: Algebra.Combinatorics, Analysis.ComplexFunctions Something like this seems like a really good idea. > Another kind of tag I > think would be useful is one that states whether something is at the > Beginner, Intermediate, or Advanced level. Interesting > I spent hours manually scanning through the Sage documentation in > order to extract the above list of functions. If a documentation > tagging system were in place, however, I think I could have written a > program that would have extracted these functions automatically. Yep. > Having presented the idea of categorizing Sage's documentation by > using tags, I have the following 2 questions: > > 1) What do people think of this idea? I like it. > 2) What would the Trigonometry tag look like if it were added to the > math_categories.txt file? I'm not quite sure I understand the question. By I could imagine that the sine function's documentation would have SUBJECTS: Trigonometry, William --~--~-~--~~~---~--~~ To post to this group, send email to sage-support@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-support URLs: http://sage.math.washington.edu/sage/ and http://sage.scipy.org/sage/ -~--~~~~--~~--~--~---
