[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Tutorial length. The Parallel Book

From: Gilles LAMIRAL
Subject: Re: Tutorial length. The Parallel Book
Date: Mon, 29 Jan 2018 16:06:24 +0100
User-agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.5.2

Hi Ole,

I give some comments about the Parallel Book

Maybe remove "2018", next years will come sooner than expected.
Suggestion: "The GNU Parallel Book"

About the reading levels : 5 levels looks too much,
just 2 or 3 levels at max is simpler for the reader and for you the writer.

* level 1: for beginners & basic users. One bar |
* level 2: for advanced users. Two bars ||
* level 3: for hardcore, source code users. |||

Another point, the system bar, if any, should be self-evident.
The current five levels system is not self-evident at all,
I see 2 bars, it means level 2, but no: it's level 5 indeed.
I see 1 bar, well, it's what level actually?

The initial tour, chapter 2, at level 1 only, is a very good thing,
it's the tutorial for beginners I need when I start using a tool.

The other chapters are also well classified. But instead of
mixing level 1 and level x several times in the same chapter,
starting with level 1 and increasing difficulties to next level
could bring an easier way to learn and master Parallel.

The constant questions the reader asks himself are:
 * "Where am I?"
 * "Should I skip what I'm reading? Will I miss something relevant?"

Initial tour of 5 minutes

Ole, it took me 25 minutes to read and apply this initial "5 minutes" chapter 2.
I used copy/paste for the examples and I was already familiar with parallel.
Those 25 minutes don't include the comments I'm writing now.

2.1 Input sources

The sentence "The values are put after ::: :" is very ambiguous!
Is it a typo? 3 ::: or 4 :::: (I do understand what the last is but
it is not a good punctuation character in the Parallel context.

2.2 Building the command line

Typo: "It can contain contain a command"

Another ambiguous sentence due to punctuation mark:
"The command line is put before the :::."

Suggestion: The command line is put before the three consecutive colons ::: 

 --dry-run could be called --dry (I'm lazy)

 2.4 Controlling the execution

 For the -j parameter, instead of the wget, I suggest to test two
 similar commands

   parallel -j2   sleep {}';' echo {} done :::  5 4 3 2 1 6 7 8 9 2 2 1 0

   parallel -j20  sleep {}';' echo {} done :::  5 4 3 2 1 6 7 8 9 2 2 1 0

The second demonstrates what happens when all sleep commands are launched
in parallel, all the "sleep x" finish at the nearly same time, after x seconds.
The first demonstrates the sequential behavior forced by the "2 runs at the 

Of course, that's just suggestion, you're the master!

Le 11/01/2018 à 03:01, Ole Tange a écrit :

So I have started writing the 'GNU Parallel 2018'-book. The first
version I tried doing as you suggest, but it really did not work well
for me: Depending on your situation you need to dive deep into one
concept without having to know much about the other concepts (e.g.
maybe outputting to CSV is key for you, but the rest of the default
settings are fine).

This suggests that 2 levels are enough.

The concepts hardly overlap, thus it will make perfect sense to be an
expert in output-options without knowing more than the basics about
remote execution.

This reinforces that 2 levels are enough.
Let the reader decides what level is his for any part,
once he's no longer a beginner, he is an advanced user for that part.

So instead I have tried dividing the book in parallel: So each section
has all information in all details, but the margin has a legend that
tells you how advanced the paragraph is. Thus you are encouraged to
skip to the next paragraph at your reader level.

The book is heavily based on parallel_tutorial.

I welcome reader's feedback on it. I have uploaded the current
(extremely incomplete) draft at
Open in LibreOffice.

Most important feed back would be: Does this marking of the reader
level in the margin work?

Not well for me, as explained above.

Well chosen examples are also keys to understand a concept,
I'll try to give the ones that make sense to me while
I learn parallel.

Au revoir,
Gilles Lamiral. France, Baulon (35580)
mob 06 19 22 03 54
tel 09 51 84 42 42

reply via email to

[Prev in Thread] Current Thread [Next in Thread]