Re: Specifying location of bibliography in document

[Daniel Staal <DStaal-Jdbf3xiKgS8@public.gmane.org>]

--As of August 31, 2015 8:12:10 PM +0200, Pablo Rodríguez is alleged to 
have said:

> On 08/31/2015 10:57 AM, BP Jonsson wrote:
>> While I share your (Pablo's) irritation over the {X,HT}ML syntax for
>> divs and spans every bit I think it is important not to confuse that
>> issue with the any questions about the uses of divs or spans, which are
>> orthogonal.
>
> Many thanks for your reply, BPJ.
>
> Sorry, but I gave up trying to explain pandoc (or Markdown) to anyone. I
> was writing a manual in Spanish, but I’m afraid Markdown is too
> complicated to explain to people with no background in text tagging.
>
> Probably I’m wrong in expecting that pandoc could replace word
> proccessing programs for average users.

Probably true.  There are Markdown editors that aim for that market, but 
pandoc isn't an editor.  It's a converter.  The editors give you a nice 
WYSWYG interface, or at least something close, and give easy shortcuts to 
common markup.

>> In principle we could use any markup to signal "the
>> references go here", but the idea that that markup should be independent
>> both of any particular place in the document and of the header (if any!)
>> used for the references section is a sound one, and the marked div
>> solution is a good one, semantically speaking.
>
> I didn’t eman that the the solution was wrong semantically speaking.
>
> My point is that this would be harder to understand for average people.
> Since we already have section divisions, using them to implement
> bibliographies placing would be easier to be understood by a new user.

Except the only actual section divisions we have are divs.  Headers don't 
create new sections.  (Well, there is an option to make them create such, 
but semantically and under normal use I've often seen headers within a 
section; sub-sections, or just breaking up the flow of the text.)  They 
often are placed at the start of new sections, but not always.

> Extra paragraphs could be added as explained. And hidding a title should
> be an easy task.

Yes, but it'd be confusing, and inconsistent.  ;)  This 'visible' marker 
(which makes things *more* visible) in one case would now hide the text 
instead.  Depending on what the text was, basically.  Which will eventually 
surprise someone.

(And note that with the above mentioned option to make headers 
automatically create divs, you could still use your version of the markup.)

> The problem I see with Markdown (and I’m afraid CommonMark doesn’t
> solve it) is that markup is inconsistent for ordinary people.
>
> The simplest rule: paragraphs are formed by consecutive non-empty lines.
> Only a blank line builds a new paragraph. Well, and what happens with
> titles?

I honestly think you're over-thinking this.

Titles aren't paragraphs; they are a single line of text.  *Don't* try to 
explain them in terms of paragraphs.  Simply say that a titles are a single 
line of text marked up in one of the ways that denotes a title.

A paragraph is any consecutive non-empty lines that *aren't* something 
else.  That 'something else' could be a title, or a list, or a table, or a 
code block, or a line block, or a quote block, or anything else that I'm 
missing or gets implemented in the future.  (Some of which can contain 
paragraphs, of course.)  We usually shorten it because people tend to 
understand 'this is a paragraph, and this is how you do $X instead of a 
paragraph' quite well.

> It is a consistent rule for computers (in fact they are two). But The
> previous rule isn’t consistent for persons.

I just listed seven.  ;)  Or one, depending on how you look at it.

And that's really my point: You're looking at it as seven, when really it's 
the one.  You're the one trying to go top-down and define it the 
complicated way.

> Sorry, this is the reason I want to use pandoc, but I won’t try to
> explain unnecessarily complicated exceptions.

But the exceptions are the rule: A paragraph is what isn't something else. 
*Everything* is an exception.  And that's really what makes Markdown and 
CommonMark clean: You only mark up what needs to be differentiated from the 
main text.

In the end, if you don't want exceptions, you end up with something like 
XML, which has a lot of visual noise because *everything* has to be covered 
in the 'normal' case.

Daniel T. Staal

---------------------------------------------------------------
This email copyright the author.  Unless otherwise noted, you
are expressly allowed to retransmit, quote, or otherwise use
the contents for non-commercial purposes.  This copyright will
expire 5 years after the author's death, or in 30 years,
whichever is longer, unless such a period is in excess of
local copyright law.
---------------------------------------------------------------

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/13393D201344655C5B10B6A5%40%5B192.168.1.50%5D.
For more options, visit https://groups.google.com/d/optout.