First, keep in mind that nothing gets committed without review, unless you already have push privileges.
In the absence of being able to actually construct the change, I like the idea of tagging things that need fixing. You can do that just by editing the document to say "This needs to be clarified in the following way:". It's not a real pull-request and wouldn't be merged, but it's an effective reminder. --Tim On Monday, January 05, 2015 11:32:11 AM ivo welch wrote: > documentation is a tricky thing. I am pretty sure you do *not* want > me to make doc changes. > > I am very qualified to state exactly where I am getting confused and > where it could be better. alas, if I tried to write it, I would write > incorrect explanation, which would probably be worse. so, this needs > one person who is learning it (the consumer) and one person who is > teaching it (the producer). > > what we really need is the ability for readers to attach questions and > notes to specific spots, that someone with knowledge can address later > on at his/her convenience. the more specific the insertion point for > comments is, the easier it will be for the writer of the documentation > to fix this later. > > fwiw, I have written a textbook in corporate finance. I needed > student reviewers that told me where they got confused. the material > was obvious to me. I don't think there is any other way to make > writing clear. > > in the absence of ability to change github to allow specific insertion > points, I wonder if we want to branch the docs and request that > comments be left in a particular color (say, red). > > regards, > > /iaw > > ---- > Ivo Welch ([email protected]) > http://www.ivo-welch.info/ > J. Fred Weston Distinguished Professor of Finance > Anderson School at UCLA, C519 > Director, UCLA Anderson Fink Center for Finance and Investments > Free Finance Textbook, http://book.ivo-welch.info/ > Exec Editor, Critical Finance Review, > http://www.critical-finance-review.org/ Editor and Publisher, FAMe, > http://www.fame-jagazine.com/ > > On Mon, Jan 5, 2015 at 2:35 AM, Sean Marshallsay <[email protected]> wrote: > > Hi Ivo > > > > You're more than welcome to contribute to the documentation yourself to > > help clarify anything you found confusing. > > > > Regarding your second point, open() does not return a named type it > > returns > > a tuple containing some kind of stream and some kind of process, Pipe is > > some kind of stream and Process is some kind of process. Hopefully the > > following code snippet will help clear things up. > > > > julia> x = open(`less`) > > (Pipe(closed, 0 bytes waiting),Process(`less`, ProcessExited(0))) > > > > julia> y = typeof(x) > > (Pipe,Process) > > > > julia> typeof(y) > > (DataType,DataType) > > > > help?> issubtype > > INFO: Loading help data... > > Base.issubtype(type1, type2) > > > > True if and only if all values of "type1" are also of "type2". > > Can also be written using the "<:" infix operator as "type1 <: > > type2". > > > > julia> issubtype((Base.Pipe, Base.Process), (Base.AsyncStream, > > Base.Process)) > > true > > > > help?> super > > Base.super(T::DataType) > > > > Return the supertype of DataType T > > > > julia> super(Base.Pipe) > > AsyncStream > > > > julia> super(Base.Process) > > Any > > > > So what we can see is that open() does return a (stream, process) tuple > > but > > stream should actually be called AsyncStream and process should actually > > be > > called Process. > > > > Hope this helps > > Sean > > > > On Monday, 5 January 2015 06:59:31 UTC, ivo welch wrote: > >> I am reading again about the type system, esp in > >> http://julia.readthedocs.org/en/latest/manual/types/ . I am a good > >> guinea > >> pig for a manual, because I don't know too much. > >> > >> a tuple is like function arguments without the functions. so, > >> > >> mytuple=(1,"ab",(3,4),"5") > >> > >> is a tuple. good. > >> > >> what can I do with a typle? the manual tells me right upfront that I can > >> do a typeof(mytuple) function call to see its types. good. > >> > >> alas, then it goes into intricacies of how types "sort-of" inherit. I > >> need a few more basics first. > >> > >> I would suggest adding to the docs right after the typeof function that, > >> e.g., mytuple[2] shows the contents of the second parameter. the julia > >> cli > >> prints the contents. the examples would be a little clearer, perhaps, if > >> one used a nested tuple, like (1,2,("foo",3),"bar"). > >> > >> before getting into type relations, I would also add how one creates a > >> named tuple. since open() does exactly this. well, maybe I am wrong. > >> the > >> docs say it returns a (stream,process), but typeof( open(`gzcat > >> d.csv.gz`) > >> tells me I have a (Pipe,Process). > >> > >> I know how to extract the n-th component of the open() returned tuple > >> (with the [] index operator), but I don't know how to get its name. > >> x.Pipe > >> does not work for open(). > >> > >> well, my point is that it would be useful to add a few more examples and > >> explanations here. > >> > >> regards, > >> > >> /iaw
