Re: Tutorial length. The Parallel Book

[Ole Tange]

Thanks for the feedback.

Before you reply checkout newest version:
https://gitlab.com/ole.tange/gnu-parallel-book

On Mon, Jan 29, 2018 at 4:06 PM, Gilles LAMIRAL
<gilles.lamiral@laposte.net> wrote:

> Title
> Maybe remove "2018", next years will come sooner than expected.

The reason for this is that I expect to find errors and improvements,
so GNU Parallel 2019 is expected to be a revised version of 2018,
maybe with another chapter or similar, but not a completely new book.

But in contrast with the manual of GNU Parallel I do not expect to
release a new book every month.

> 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. |||

The reason for the weird encoding is that I have been unable to get
LibreOffice to give me 3, 4 or 5 bars. Otherwise that would be obvious
for level 3-5.

> Another point, the system bar, if any, should be self-evident.

I am not sure what you mean by "the system bar".

> 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.

Again a limitation in LibreOffice: There are 2 levels with 2 bars:
level 2 (in thin bars) and level 5 (in fat bars), but unfortunately if
you do not zoom in close enough that may look the same.

All in all it tells me that _if_ I want to go with 5 levels, I need to
find better encoding for level 4+5 (and possibly 3). In the newest
version the bars for 4+5 are fatter.

> 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.

That is the way I am finding really difficult to write in. Let us take
an example.

In 4.1 I write about a single input source, but it is obvious that a
beginner will never need using a FIFO or command substitution as a
single input source. Therefore FIFO/command substitution are
classified as level 4 whereas the rest is level 1.

If I do not mix the levels, then I will need another section about
single input source, which would then be level 4. This means that I as
an advanced user would now have to look two different places in the
book to find the information.

Can you try to elaborate on how you envision the above could be written?

> The constant questions the reader asks himself are:
>  * "Where am I?"

Do you mean: "What level am I?" or do you mean "What section in the
book am I reading?" or do you mean something else?

>  * "Should I skip what I'm reading? Will I miss something relevant?"

The goal is to ensure the reader can see the book as 5-books-in-1:
Read all level 1 and you will have a full consistent book where you
skip nothing relevant. Or read all level 1+2 and you will have a fully
consistent book where you skip nothing relevant. Or read all level
1+2+3, and it is still a book, or level 1+2+3+4.

If that goal is not clear, then help me phrase a text that will make
that clear in chapter 1.

In practice you should for most parts be able to change level for each
chapter: So you can be a level 5 in "4 Input sources", while being a
level 1 in "8 Remote execution" (because you never use that), and a
level 2 in "9
Pipe mode" because you only use the basic functionality in --pipe.

Again: If that is not clear, help me rephrase chapter 1.

I feel that by mixing in the more advanced stuff, the reader can get a
feel of, what the higher levels cover, but at the same time reader
should confident to skip these parts, if they are too hard to
understand.

> 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.

The typography for the options and syntax in the text need to have its
own typography that stands out from the rest. I will make a revision
of that, and hopefully that will stand out enough that it is clear.

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

It also has an alias: --dr if you are really lazy. I try, however, to
use the --long-format when introducing the option, so that the reader
knows what the abbreviation stands for, and thus it might be easier to
remember the abbreviation.

>  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
> time"
> restriction.

I think that is a valid point. I was trying to use an example that I
have actually run in real life, but real life examples should be in
another part of the book, which can the reference the relevant
sections of the book.

> Le 11/01/2018 à 03:01, Ole Tange a écrit :
>
> 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.

Let me try to argue for the more-than-2 levels with a concrete example:

If you just need to run wget on a bunch of URLs in parallel, you are level 1.
If you need {= perlexpr =} in your command you are level 2.
If you are going to define your own replacement strings or need to use
pre-defined dynamic replacement strings, you are level 3.
If you need to define your own dynamic replacement strings, you are level 4.
If you want to know implementation details on dynamic replacement
strings, you are level 5.

Understanding how to define a dynamic replacement string and why they
are useful, can be waaay too deep for a level 2 user, that just wants
to run a simple perl expression on the input.

If you want a 2-level approach which of the above 5 levels would you
consider level 2?

>> Most important feed back would be: Does this marking of the reader
>> level in the margin work?
>
> Not well for me, as explained above.

I feared as much. I hope the new revision has improved that.

> 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.

I think I will make a chapter with examples with explanations and
references on where in to book the used options are covered. This way
I do not need to limit the examples to options that the readers had
learned at this time.

/Ole