[pmwiki-users] Delete EditGettingStarted, haracterMarkup, LineMarkup (and more)?

[john.rankin at affinity.co.nz]

>>
>>So while the information is a repetition of that found elsewhere,
>>the pages are not necessarily redundant. Of course, they may
>>not be fulfilling their intended purpose either.
>
> Although I generally agree with you that an alternate view and a quick
> and easy introduction could be useful, I have several problems with
> _this_ cluster of pages:
>
> - I don't see that the absolute beginner even would find these pages
> since they are not linked from outside (besides BlockMarkup).

I agree. Either the pages should be revised and linked to the rest
of the documentation, or deleted. I propose an alternative at the
end of this post: delete these pages, but refactor the PmWiki
documentation around the Creole standard as "the core markup set".
>
> - The pages are not very well maintained IOW not up to date and maybe
> not even correct.

I agree.
>
> - The terminology differs from that of the other documentation.

To an extent, this is deliberate, in that the pages try to explain how
the markup is put together, whereas (IMO) all the other documentation
pages are designed to look up markup when you already know what
you are looking for.
>
> - IMO they are not easier to understand than BasicEditing and
> TextFormattingRules.

What I would really like to do is ask a new user, who has never
used a wiki before and does not know what markup is, what
kind of documentation would help to get started and whether
BasicEditing and TextFormattingRules are suitable for this.

I feel as if I am speculating and offering an opinion without
supporting evidence. (See Creole-based proposal later.)
>
>>Just my 10? worth.
>>>
>>> LineMarkup: Wrong title, redundant.
>>
>>What would be a correct title? I have never known what to call
>>markup that starts a line and affects the behaviour of the whole
>>line and only the line. Start-of-line markup? Line markup seems
>>simpler and clearer to me.
>
> A heading is a structural element, not "formatting". A list item can
> span more than a line and is also more structural than "formatting".
> Indented or hanging paragraphs are also not "lines". I don't
> understand "Compound line markup": '->' is _one_ markup, nothing
> compound.

I think we are in almost total agreement on this, except for the
definition of "line". I think we might be defining "line" slightly
differently. In "line markup" usage, a line ends with 1 or 2 return
characters. So a list item is one line.

* a list item

is line markup -- one line (no matter how long) -- whereas:

[=
some text
some more text
=]

is block markup (in this classification scheme), as it spans more
than one line.

To a degree, the distinction is an artificial one, but it gives a way to
structure the long list of markup rules into smaller groups.

I think I agree that the "compound" line markup could be
unnecessary.  It is a way to distinguish between simple markup
(start a line with an asterisk to create a list item) and "compound"
markup like :term element: definition text.
>
> <splitting hairs> According to this definition, lists and paragraphs
> would be block markup - both are described in LineMarkup. </splitting
> hairs>

Not true. As defined, a line ends with a return character followed
either by a second return character or by a line markup character.
There is no block wiki markup for lists, only a collection of lines.
The defining characteristic of block markup is that there are
opening and closing markup pairs, with one or more lines in
between. Neither a list item nor a paragraph fits this definition.
>
>>Under this definition, the bottom part of the page does indeed
>>describe block markup, whereas the top part of the page now
>>suggests that "block markup" is only about wikistyles.
>
>
> Note that the description of [@ @] and [= =] in BlockMarkup differs
> from Site/EditQuickReference, BasicEditing, TextFormattingRules at
> least regarding the terminology.

This is true. One result of introducing character, line and block
classification is that [@ ... @] and [= ... =] can be used as both
character markup and block markup. This is both a strength
and a weakness of the classification scheme.
>
>>If these pages are deleted, there is AFAIK nowhere else in the
>>documentation that offers a logical way to understand wiki
>>markup. Exhibit A is TextFormattingRules and Exhibit B is
>>MasterMarkupIndex. It seems a shame to lose the markup
>>classification scheme (grammar) that these pages present.
>
> I'm afraid I don't understand what you want to express - please bear
> in mind that English is a foreign language for me.
>
> IMO EditQuickReference, BasicEditing and TextFormattingRules give a
> very well introduction to PmWiki markup.
>
> After revisiting this topic _very_ thoroughly, I still don't see the
> benefit of EditGettingStarted, CharacterMarkup, LineMarkup over
> EditQuickReference, BasicEditing and TextFormattingRules. But I'm not
> sure enough to delete them without support from others.

FWIW, my view is that PmWiki's markup set now presents a very
high barrier to entry for new users, especially those who are new
to wiki markup.

I do not have a good answer to this and your posts are convincing
me that the pages in question are not fit for their intended purpose.
Let me suggest an alternative for discussion. We now have the
Creole markup standard which gives a core markup set that every
wiki ought to offer as a minimum. AFAIK, the Creole set was a very
carefully chosen balance between power and simplicity.

My proposal is that an IntroductionToPmWIkiMarkup page presents
PmWiki's markup rules for the Creole markup functions, in the
order they are described in the Creole standard. See
http://www.wikicreole.org/

For avoidance of doubt: the Introduction page would contain
*only* the Creole markup set, no matter how much we might
want to include "just one or two more features".

I would be very happy to see the PmWiki documentation factored
to use the Creole set as an introduction, with branches to more
advanced markup features. This does not require PmWiki to adopt
the Creole standard, just use the Creole thinking. I think I would
also refactor EditQuickReference to present only the Creole markup
set, with links to other markup features. Or at least separate the
Creole set from anything else that may be on the quick reference
page.

JR