Re: Specifying location of bibliography in document

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

(Trimmed)

--As of September 1, 2015 7:55:18 PM +0200, Pablo Rodríguez is alleged to 
have said:

> On 08/31/2015 09:29 PM, Daniel Staal wrote:
>> --As of August 31, 2015 8:12:10 PM +0200, Pablo Rodríguez is alleged to
>> have said:

>>> 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.
>
> Many thanks for your reply, Daniel.
>
> The problem with visual editors is that users many not know what they
> are actually doing.
>
> In that case, I think there is no gain in using pandoc.

There is some gain - the markup is structurally simpler than many others, 
and it's more cross-platform and widely specified.  Basically, you get a 
more compatible and easier to work with file, even if the users don't 
directly deal with it.

>> 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.
>
> It may be my own approach to sections and their titles. Being able to
> wrap a section with title and contents into a division is essential to
> format chapters (or other sections) such as copyright, dedication,
> epigraph and colophon pages as different from other chapters.

True, but that's not the only way they are used, just the most common, 
especially in longer works.

>>> 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.)
>
> My comments don’t make sense now, because the implemented solution
> allows to add text both before and after the bibliography. I hadn’t
> thought of that possibility.
>
> My comment now is to avoid using XML syntax, since it is harder for
> newcomers.

Yeah, there's was a lot of discussion over the HTML syntax.  (It's more 
HTML than XML, really, even though HTML is basically a subset.)  And other 
syntaxes...

Basically, no one could agree on what a more Markdown-like syntax was, and 
since Markdown passes through HTML syntax a temporary solution was to 
enable reading of the HTML.  If someone can come up with a good Markdown 
syntax for divs and spans I think John's still open to adopting it, but the 
current syntax doesn't prevent that and it *was* agreed that divs and spans 
were needed.

So, to sum up: This works, and if you have a good idea for what the syntax 
for a div or a span *should* be, we're all ears.  ;)

>>> 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.
>
> It may be. My fundamental mistake may be be trying to make sense of
> Markdown as lightweight markup.
>
>> 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.
>
> It was only a minor issue. But do you really think that there is a need
> to limit titles to a single line? In other words, does this exception
> make sense?
>
> I’m not trying to change it (mainly because of backwards compatibility),
> but I don’t see any reason to handle titles as block elements in a
> different way from paragraphs (in regard to this rule).

Well, first off, they aren't really titles.  They are *headings.*  (There's 
only one title per document, after all...)  And part of this is explained 
by Markdown's roots as a text-to-html converter; HTML heading elements are 
block elements that can't contain other block elements (like paragraphs), 
so it was basically assumed.

But in general, I can see your point.  There's no real reason to assume a 
heading is any specific length.  Practically, you don't want a heading 
that's to long because most people won't read it, but that doesn't 
necessarily mean we should limit it.

On the other hand, *most* titles are something that will fit into one easy 
line.  (And note that Pandoc doesn't limit the length of a line...)  One of 
the things I like about Pandoc is that it's a 90% solution - it doesn't try 
to cover every last possible variation, if that would unnecessarily 
complicate the markup.   Keeping headings to one line makes the markup 
simple and easy to read, and covers 95+ percent of actual use, so it may 
not be worth complicating the markup just to cover a few more final percent 
of use-cases.  If you really need some fancy long multi-line title, you 
probably will want it laid out and viewed in a specific way for your use, 
and there are usually programs specifically designed for that use that you 
can do that with.  (Even if you are giving up the convertablity and ease of 
use of Markdown.)

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/FCFE2CE2278E42B31A8E30AE%40%5B192.168.1.50%5D.
For more options, visit https://groups.google.com/d/optout.