[Swift-devel] user guide work

Mon May 18 17:50:40 CDT 2015

On Mon, 2015-05-18 at 17:04 -0500, Ketan Maheshwari wrote:
> I would argue in favor of some redundancy between user-guide and
> tutorial. Assuming that most users are busy (and impatient), they will
> randomly click one link and we will have a better chance to get the
> point across.

I'm not sure what you are saying. Can you be more specific? With
examples perhaps?

> 
> I think we should collaboratively develop a ToC for user-guide and
> tutorial before filling in the details. I think most details exist
> already, it is a matter of figuring the placements.

As long as we are on the same page about what we want to achieve, then I
think that's a good idea.

But I disagree that the details are there and that this is a matter of
shuffling paragraphs around. The details we have are lousy, the grammar
is lousy, and many things are incorrect. I can give many examples, but
let's just pick one:

-------------
Sequential iteration can be expressed using the iterate construct:

step[0] = initialCondition();
iterate ix {
  step[ix] = simulate(step[ix-1]);
}
This fragment will initialise the 0-th element of the step array to some
initial condition, and then repeatedly run the simulate procedure, using
each execution’s outputs as input to the next step.
-----------

The code doesn't work (it's missing the "until"), the step array is not
a condition array (it can be anything). The code also doesn't work
because it will deadlock on step[-1], because the initial ix is 0.

This snippet is in "Arrays and parallel execution", except iterate does
not do parallel execution. The first paragraph of that section reads:

-------------
Arrays of values can be declared using the [] suffix. Following is an
example of an array of strings:

string pets[] = ["shane", "noddy", "leo"];
An array may be mapped to a collection of files, one element per file,
by using a different form of mapping expression. For example, the
filesys_mapper maps all files matching a particular unix glob pattern
into an array:
-------------

What's a "different form of mapping expression"? (the context for that
is many paragraphs earlier). There is absolutely no mention of parallel
execution or parallelism in the section titled "Arrays and Parallel
Execution".

Furthermore, Swift has evolved a lot since that documentation was
written, and very little of that is documented. So no, the details are
not there.

Mihael

> 
> --
> Ketan
> 
> On Mon, May 18, 2015 at 4:48 PM, Yadu Nand Babuji <yadunand at uchicago.edu> wrote:
> > The overview sounds a lot like the tutorial. I think it's better to have
> > tutorial-like material just go into the tutorial rather than just get
> > duplicated in the userguide.
> > If the tutorial does not give the user an adequate picture of items in
> > Ketan's overview, the tutorial needs fixing.
> >
> > The webpage points users to the tutorial, and if the tutorial isn't
> > adequately covering the useful 20% of the language, I suspect that they
> > wouldn't bother to get to the userguide.
> >
> > Thanks,
> > Yadu
> >
> > On 05/18/2015 04:34 PM, Ketan Maheshwari wrote:
> >> This is true except for the first chapter. First chapter is going to
> >> be read by a significantly larger number of people and the rest of it
> >> would be ctrl-f'd. I think we may want to push some stuff further down
> >> in the user guide than what is in the link you originally posted.
> >>
> >> --
> >> Ketan
> >>
> >> On Mon, May 18, 2015 at 4:18 PM, Mihael Hategan <hategan at mcs.anl.gov> wrote:
> >>> Right. This is pretty close to what K&R does.
> >>>
> >>> I was personally thinking the following: intro, language reference,
> >>> runtime reference, tools reference. It's not trying to sell anything or
> >>> emphasize anything. You use it when you need answers. You don't really
> >>> read it. You scan it for what you need, and then read the parts that are
> >>> relevant to what you are trying to do. The order is from basic concepts
> >>> to more complex ones. It's an order that most people would expect,
> >>> especially people that have little experience with swift. It is like
> >>> that because the purpose is for a user to quickly find the information
> >>> they need, not for us to point out to users what we think is cool about
> >>> our stuff.
> >>>
> >>> What you describe is fine. And there is no reason why the two things
> >>> cannot coexist. Which is the general idea that I think we discussed
> >>> during the last meeting. There's formal documentation and there's
> >>> informal introductions / tutorials. The latter are different. You read
> >>> them sequentially, like a book. The order is the order in which things
> >>> are important in swift. You wouldn't start with types and variables.
> >>>
> >>> Mihael
> >>>
> >>> On Mon, 2015-05-18 at 15:27 -0500, Ketan Maheshwari wrote:
> >>>> I think a little bit of both.  A brief overview of important things
> >>>> with examples in chapter 1. Then, topics like "Task Parallel
> >>>> Computing" or "Many Task Computing" may cover foreach, futures and
> >>>> task parallelism as implemented in Swift. Then, a chapter like "File
> >>>> I/O" may cover the mappers, etc. Then a topic like operators and
> >>>> variables may bring in more of the language reference in that
> >>>> describing types, structs, etc. Next may be builtin functions.
> >>>> Followed by a chapter on Compute sites which covers Resource and data
> >>>> managers, remote access and providers and such.
> >>>>
> >>>> So, to elaborate here is a rough outline I have in mind:
> >>>>
> >>>> Chap 1. Swift Overview
> >>>> -- Importance of Swift
> >>>> -- Swift example 1
> >>>>     -- hello world, description, concept show in this example
> >>>> -- Swift example 2
> >>>>     -- Run an app functions, describe importance of app functions
> >>>> -- Swift example 3
> >>>>     -- Do file mappings, describe mappers
> >>>> -- Swift example 4
> >>>>    -- Do foreach loop, describe foreach
> >>>> -- Swift example 5 (if needed)
> >>>>
> >>>> Chap 2. Many Task Computing in Swift
> >>>> -- Parallelism in DAGs
> >>>> -- Futures
> >>>> -- foreach loop and variants
> >>>> -- iterate
> >>>>
> >>>> Chap 3. File I/O
> >>>> -- File types
> >>>> -- Simple file def
> >>>> -- Complex Mappers
> >>>> -- Read and Write to Files
> >>>>
> >>>> Chap 4. Variables and Operators
> >>>> -- types
> >>>> -- structs
> >>>> -- import
> >>>>
> >>>> Chap 5. User defined and Builtin functions
> >>>> -- string
> >>>> -- numerical
> >>>> -- stat
> >>>> -- math
> >>>>
> >>>> Chap 6. Swift providers
> >>>> -- Coasters
> >>>> -- Data providers
> >>>> -- Compute Providers
> >>>>
> >>>> Chap 6. Remote compute sites
> >>>> -- Modes of running
> >>>>
> >>>> Appendix A. Swift Grammar in BNF
> >>>> Appendix B. A table of Swift conf options
> >>>> Appendix C. Swift cheatsheet
> >>>>
> >>>>
> >>>> On Mon, May 18, 2015 at 2:20 PM, Mihael Hategan <hategan at mcs.anl.gov> wrote:
> >>>>> On Mon, 2015-05-18 at 13:27 -0500, Ketan Maheshwari wrote:
> >>>>>> I think Swift is a special purpose language where ~20% of features are
> >>>>>> used for ~80% of cases. Consequently, providing a K&R style language
> >>>>>> manual might not be the most valuable thing for a user to read. It
> >>>>>> also runs a risk of coming across as a general purpose language which
> >>>>>> may mislead readers.
> >>>>>>
> >>>>>> I think, a document structure where the important features (app and
> >>>>>> builtin functions, variables and mappers (with examples)) are
> >>>>>> highlighted in the early parts and details such as variable scope,
> >>>>>> expressions, operators etc. are described in the middle and concluded
> >>>>>> with sites specific details might serve well.
> >>>>> You mean like a brief overview of important things / tutorial in the
> >>>>> beginning?
> >>>>>
> >>>>> Or do you mean that the language reference should not have a bottom-up
> >>>>> structure, starting with the simple/primary concepts and building up
> >>>>> from that?
> >>>>>
> >>>>> Mihael
> >>>>>
> >>>>>> --
> >>>>>> Ketan
> >>>>>>
> >>>>>> On Sat, May 16, 2015 at 4:04 PM, Mihael Hategan <hategan at mcs.anl.gov> wrote:
> >>>>>>> Hi,
> >>>>>>>
> >>>>>>> Mike pointed out that I should probably post a link to what I'm trying
> >>>>>>> to do with the user guide just in case things are going awfully wrong.
> >>>>>>> So here it is:
> >>>>>>>
> >>>>>>> http://www.mcs.anl.gov/~hategan/ug/ug/ug.html
> >>>>>>>
> >>>>>>> Mike mention K&R a number of times and I think I like that general idea.
> >>>>>>> The above, so far, is a mix between K&R Chapter 2 and Appendix A.
> >>>>>>>
> >>>>>>> The main idea is to keep things concise by separating parallelism
> >>>>>>> behaviour from what a program actually does. In that sense, one would
> >>>>>>> first describe the language, and then go into the details of how a
> >>>>>>> particular implementation goes about running programs.
> >>>>>>>
> >>>>>>> I'm not particularly opposed to starting with a brief tutorial in the
> >>>>>>> spirit of K&R Chapter 1.
> >>>>>>>
> >>>>>>> Mihael
> >>>>>>>
> >>>>>>>
> >>>>>>> _______________________________________________
> >>>>>>> Swift-devel mailing list
> >>>>>>> Swift-devel at ci.uchicago.edu
> >>>>>>> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel
> >>>>>
> >>>>> _______________________________________________
> >>>>> Swift-devel mailing list
> >>>>> Swift-devel at ci.uchicago.edu
> >>>>> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel
> >>>
> >>> _______________________________________________
> >>> Swift-devel mailing list
> >>> Swift-devel at ci.uchicago.edu
> >>> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel
> >> _______________________________________________
> >> Swift-devel mailing list
> >> Swift-devel at ci.uchicago.edu
> >> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel
> >
> > _______________________________________________
> > Swift-devel mailing list
> > Swift-devel at ci.uchicago.edu
> > https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel
> _______________________________________________
> Swift-devel mailing list
> Swift-devel at ci.uchicago.edu
> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel