Re: spacing before items

[Henning Hraban Ramm <texml@fiee.net>]

> Am 24.06.2020 um 19:41 schrieb Mike Cooper <mike@murchisondrillingschools.com>:
>> <Hans>
>> Indeed. It's all volunteer work that doesn't pay the bills. Sitting down
>> and starting to write a big manual simply doesn't pay off so it has to
>> happen in free time. And that being the case, it is more attactive to
>> work on some new challenge.
>> 
>> Concerning manuals: I sometimes wonder if they are really read. So, how
>> to set up one that works for all, build up explanations, etc ... isn't
>> it more about googling a solution nowadays (ok, not entirely true i
>> guess, as one then has to learn how to distinguish the wrong solutions
>> from the good, but i suppose one can just test it).

Most of you know I’m writing at this German ConTeXt book since years...
I use the incomplete version myself a lot, and I very much hope that at least every second German TeX user will buy it ;)

And of course it’s a lot of work – while Hans, Wolfgang and Taco (and a few otehrs) know their code, I must look up every option, try to find a short description or come up with a test case, so that I understand what’s going on to write it down for others. (Often parallelly for the book in Germand and for the wiki in English.)
And far too often I give up because I can’t make something work – mostly because I didn’t understand some fundamental concept (expansion...), but sometimes features just don’t work as advertised/documented (like columnsets).

Googling is necessary and helpful for LaTeX, but there aren’t so many blog or forum entries about ConTeXt.

> I started out maybe a little bit hodge-podge, looking through some documentation recommended to me.  The basic concept is very straightforward.  No problem.  But implementation has been extremely challenging (but it's probably just me!).  Then I was pointed to Henri Menke's "Definitive Guide" post.  I read the entire Excursion (though I confess I did not *practice* as I went along (partly because SciTe was such a pain)).  The Excursion is not for (true) beginners.  And, no offense, but I thought it was poorly typeset as well...

I think it doesn’t make a lot of sense to try to understand the whole thing at once.
You need to start small with a project and some basic structuring, then add your style requirements one after the other.

If you come from a layout background like me, some “advanced“ stuff is really easy in ConTeXt, while seemingly basic stuff is very hard.
The mindset of a command-based typesetting system is fundamentally different from that of a layout program or word processor – even if you can do a lot of the same tasks with each.

> Then I went through Aditya's "amazing tutorial" (mostly with a good bit of help from Aditya just to be able to get started!) and definitely learned more.  But at the end I felt like it was mostly an exercise in "slow-motion copy/paste" (I retyped all the code).  Of course, when I got the code right, I got the intended output.  I did fiddle with options a little bit as I went.  No doubt, I should have done more.  There was too much of what I had "successfully" done that I still didn't really understand at the end of it.

A typesetting system like ConTeXt is as much a tool for professionals as a layout program like InDesign. And even a word processor is better used by professionals who understand what they’re doing.

Each system is also usable by beginners (TeX not so much) – but they can’t expect to get professional results immediately.

With TeX, footnotes, ToCs and indexes are beginner stuff, while they’re quite advanced with InDesign or Word. Styling your work is much easier in a visual programm – while you do it manually.

For ConTeXt you need on one hand the mindset of a programmer, on the other hand that of a media designer.
Using LaTeX you can choose a readymade style (class), but with ConTeXt you define your own – it’s easier, but still challenging.

I think ConTeXt has a similar problem as Objective C: It might be superior to C++, but every introduction into ObjC assumes you are familiar with ANSI C or C++. But if ObjC is so great, why should I bother learning the other?
Most ConTeXt users used LaTeX or plain TeX before. They have to re-learn a lot, but they know a bit about how TeX thinks and works, and they know the limitations of LaTeX.
There is more beginner level documentation for ConTeXt than for ObjC, but we still assume a basic familiarity with TeX and principles of design and typography.

With my book I’m trying to start without prior knowledge, even if I know most of my readers will come from LaTeX.
But I still include sections about working on the command line or choosing a text editor and a lot of basic design/typography knowledge. I want it to really enable someone with usual office experience to start with ConTeXt. On the other hand I’d like to show what’s possible and what I find interesting.

And that leads to:

>> It has been said before: one can have manuals, wikis, mailing lists,
>> journals ... once they cross the beginners level they also become large
>> and hard to navigate. One can have 'beginners' and 'advanced' but who
>> wants to be a 'beginner' ... when is the line crossed. Maybe on the wiky
>> we should actually have that distinction.

It very much depends on your background what you regard beginner or advanced level.

I’m a media designer and not a (computer) scientist, so I don’t need complex formulae, and I don’t know how to describe graphics as curve sections or such, and I can’t come up with good algorithms.

But I’d like to place images on a design grid and fit them to size (maybe even consider the topical focus area) – basic in InDesign, nearly impossible in LaTeX, still very advanced in ConTeXt (with Lua).

Regarding “large and hard to navigate”: It’s sometimes a tough decision what to include in my book and what not, and even more how to order the topics. While I know I need to explain e.g. basic font switching before OpenType features and frames before tables because of the dependencies, I still want to keep topics together, even if the advanced stuff of one topic depends on later chapters.

And I don’t want to have too many chapters (also not very different sizes), so I put things together that make sense in *my* mind (e.g. titling levels and enumerations, it’s all basic structuring), but it’s unavoidable that some readers will find that confusing. (I try to compensate with good indexes.)

Would it make sense to show examples for every possible combination of options? Maybe for users that need to *see* what they’re looking for, but that would unproportionally bloat the book: I want to stop at 400 pages (still at around 270).
Such examples would make sense in the wiki, but it’s too boring and tedious writing them...


>>> I don't think I've ever been quite so frustrated at trying to learn anything else in
>> my life!  If it wasn't required by my job, I wouldn't have made it past the first day or
>> two (3 months ago).  But I'm slogging away and it's gradually coming together (I
>> think).  I spent my whole day yesterday figuring out how to do some very basic
>> formatting/layout that would have taken 5-10 minutes in Word or HTML/CSS.

But I’m quite sure if you figured it out on your own, you know how to do it next time. Or if you forget, you can look for your own solution (I recur to my old environments all the time).

May I ask what kind of job requires you to learn ConTeXt? That’s rare.

> Off the top of my head, I would suggest more explanation/description and especially more examples of what each option/key/whatever does.

See above: It would make sense, but somebody would need to do it, and it’s very tedious. There are hundreds of setup commands, each with many options, each with different values... And some options behave differently depending on other setups or work only under certain circumstances...

> I've always found w3chools.com to be especially helpful with HTML/CSS because they give plenty of examples and explanation.

Please don’t use w3fools! It’s full of errors and bad practice. (At least it was some years before; I can’t imagine it got fundamentally better.)

> I don't know if it's really feasible to do anything about it but another thing is the jargon.  I probably mainly think in terms of HTML/CSS lingo and then MS Word.  When I hunt through the wiki or the manuals or Google for solutions, I naturally use the terms I know. But it seems that the things I've wanted are referred to differently in ConTeXt.  I spent *days* trying to figure out how to add more whitespace around a floated graphic (the default is too cramped in my opinion).  I finally just threw up my hands and decided that no one else has this opinion but me so nobody has ever "fixed" it and thus, no solution exists.

Hm, did you try the margin options of https://wiki.contextgarden.net/Command/setupfloat ?

I agree you need to get used to the “lingo”. But that’s the same with every programming language or big library (like .NET or QT). Even more if you need to combine different techniques (like e.g. ConTeXt behind a Django web application that uses a Meteor frontend; i.e. TeX, Lua, Python, JavaScript/TypeScript/CoffeeScript, CSS/SASS, SQL, git, NginX/Apache, deployment tools etc.).

While I’m used to ConTeXt jargon since 20 years, it helps that I’m also used to general typesetting and design jargon. But there’s still a lot I don’t understand or I must search for.

> I don't mean to be a jerk or anything.  I'm trying to learn this stuff.  It's just extremely frustrating...

The learning curve *is* steep and stays steep for a long while, depending on your requirements.


Good luck!
Hraban
www.fiee.net / www.dreiviertelhaus.de



___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________