[Swift-devel] user guide work

[Ketan Maheshwari]

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