Developer FAQ

From Snowbird
Jump to: navigation, search

Package and Development Questions

  • How does one submit a completed packages? Are they reviewed?
  • Packages and distribution all ready, but needs work. What to do?
  • Testing a probabilistic routine? Setting random seeds (setRandomSeed).
  • Package already exists that you are working on and there are conflicts.
  • Problems from missing packages/files SimpleDoc.
  • Reinstall/uninstall of package does not replace html.
  • Common errors messages and solutions.
  • How to create new types - there should be a (long) documentation page detailing this; the current one is too cryptic.
  • How to display nicely and after prints.
  • Resolving name collisions.

If you load a package Foo and then a pacakge Bar which both have export method poset, then whenever you call poset, the method run comes from Bar. There will be warnings which tell you that the Bar poset method overshadows the Foo poset method. There are long names which allow you to access both: Foo$poset and Bar$poset will call their respective methods. Use dictionaryPath to see the order of the packages.

If the package Bar uses symbols from the package Foo, include the command needsPackage"Foo" right after you set up the newPackage syntax. If you further need the symbols in package Foo to be visible to the user, in particular, if you use them in examples in the documentation in package Bar, then you need to put the command needsPackage"Foo" before the newPackage synatax as well as after (so you will see needsPackage"Foo" twice in the package Bar).

  • Should typical values go in the method declaration or in the installation?
  • Should exported symbols be methods or functions? Methods allow for different arguments (overloading).
  • Customization of a third party package by the user.
  • How do you get access to code that you've overwritten.
  • How do you use check? (We [Adam and Sonja] were having trouble; SimpleDoc had to be in a specific directory in order to work.)
  • Should have a "what is the difference between..." page. For instance: what is the difference between function and method, between and :=
  • Maybe have an index of all method/function names in current packages. This may prevent name collision.

Documentation Questions

  • How does one write Hyperlinks in SimpleDoc?

Use the command

  @TO [function name] @  

if you want to refer to another Macaulay2 function within the package. (Not sure how to do a web page???)

  • When will a separate category for references be added to SimpleDoc?

We hope someone will do this soon.

  • How does one document multiple keys at once (this includes multi-input)?

Use the following format

  Key
    functionName
    (functionName,inputType1)
    (functionName,inputType2)
     
    (functionName,inputTypeN)
 Headline
    functionName description
 Usage
     j= functionName M1 or functionName M2 or .... 
 Inputs
   M1:inputType1
     description of M1
   M2:inputType2
     description of M2

  • Documentation optional inputs ( some functionality in Simple Doc missing)
  • It is possible to use some latex -- what and how?

Some simple tex formating commands can be done inside of SimpleDoc's Text environment. For example, \bf and \em will work. Good for accents on names! There is a promise to document what commands work in the future.

  • How do you find the file in the doctree that a doc node lives in?
  • How do you submit requests for better documentation for a particular node?
  • In SimpleDoc, when using Caveat, can you include examples? I (Adam Van Tuyl) wasn't able to do this.

(SP: I can't even use Caveat anymore; it reports an error that it does not recognize that keyword!!)

Mathematical Questions

  • How do you work with tower rings and manipulating such rings.
  • Suppose you have a module that you also want to view as a ring. Is there a way to switch between these?
  • Suppose you have matrices A and B with the same target such that A factors through B. Then the result of 'A // B' makes sense, but in principle the correct answer is only unique up to addition of matrices whose columns lie in kernel B. If there exists a matrix C such that A=BC and the entries of C are all in the ground field, is the same always true of the result of 'A // B'?