ANN: pandoc 1.15.2

ANN: pandoc 1.15.2

[John MacFarlane]

I've just released pandoc 1.15.2:

Hackage:  https://hackage.haskell.org/package/pandoc-1.15.2
Github:   https://github.com/jgm/pandoc/releases/tag/1.15.2

A changelog and binary packages for Windows, OSX, and 64-bit linux
can be found on the github release page.

Some highlights:

- ability to use ConTeXt rather than LaTeX in creating PDFs
- emoji markdown extension
- relative cell widths in pipe tables, fixing issues using
  them with LaTeX/PDF
- fixed --self-contained with CSS containing data URIs
- support start number in textile ordered lists (writer
  only)
- support Spans and Divs with lang attributes in LaTeX/ConTeXt
- many improvements to org reader
- fixed links in footnotes in docx reader
- fixed raw HTML parsing bugs in Markdown and HTML
- fixed internal links in LaTeX/PDF
- added a way to link to external resources in EPUBs, rather
  than inclding them in the EPUB container
- lots of cleaning up in LaTeX and ConTeXt templates;
  new default is not to color links

Thanks to all who contributed, and particularly to Albert
Krewinkel, Jesse Rosenthal, Andrew Dunning, and mb21.

Re: ANN: pandoc 1.15.2

[Pablo Rodríguez]

On 11/15/2015 11:39 PM, John MacFarlane wrote:
> I've just released pandoc 1.15.2:
> 
> Hackage:  https://hackage.haskell.org/package/pandoc-1.15.2
> Github:   https://github.com/jgm/pandoc/releases/tag/1.15.2
> 
> A changelog and binary packages for Windows, OSX, and 64-bit linux
> can be found on the github release page.

John,

many thanks for the new release.

One of the features I miss (or I‘m not able to find) is the ability to
place the bibliography anywhere in the document.

I don’t know whehter this has been implemented in the master branch or not.

To implement the same feature for the TOC and footnotes, consider the
following.

If you go to a bookstore (or even a library), most books may include a
TOC, some of them may have footnotes and a portion of those may include
a bibliographpy.

Implementing the ability to locate the TOC and footnotes is also
important, because they might be more frequently used with Markdown
documents.

Would it be possible that pandoc automatically-generated contents could
be placed by the user anywhere in the document?

Many thanks for your help,

Pablo
-- 
http://www.ousia.tk

-- 
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/56491E8F.4090408%40web.de.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[John MacFarlane]

+++ Pablo Rodríguez [Nov 16 15 01:08 ]:
>On 11/15/2015 11:39 PM, John MacFarlane wrote:
>> I've just released pandoc 1.15.2:
>>
>> Hackage:  https://hackage.haskell.org/package/pandoc-1.15.2
>> Github:   https://github.com/jgm/pandoc/releases/tag/1.15.2
>>
>> A changelog and binary packages for Windows, OSX, and 64-bit linux
>> can be found on the github release page.
>
>John,
>
>many thanks for the new release.
>
>One of the features I miss (or I‘m not able to find) is the ability to
>place the bibliography anywhere in the document.
>
>I don’t know whehter this has been implemented in the master branch or not.

It has been implemented in pandoc-citeproc since
pandoc-citeproc 0.8 (and is documented in its changelog).

If you include `<div id="refs"></div>`
in your document, the bibliography will be placed there.
Otherwise it will be placed at the end as before.

>To implement the same feature for the TOC and footnotes, consider the
>following.
>
>If you go to a bookstore (or even a library), most books may include a
>TOC, some of them may have footnotes and a portion of those may include
>a bibliographpy.
>
>Implementing the ability to locate the TOC and footnotes is also
>important, because they might be more frequently used with Markdown
>documents.
>
>Would it be possible that pandoc automatically-generated contents could
>be placed by the user anywhere in the document?

For toc, you can already adjust its position in most of the
templates.  You can't put it in an arbitrary position in the
middle of the document body, but I don't see why that would
be wanted.

Footnotes are harder, because they're handled automatically
in most formats.

-- 
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/20151116015102.GA18958%40MacBook-Air-2.local.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[Pablo Rodríguez]

On 11/16/2015 02:51 AM, John MacFarlane wrote:
> +++ Pablo Rodríguez [Nov 16 15 01:08 ]:
>> [...]
>> Would it be possible that pandoc automatically-generated contents could
>> be placed by the user anywhere in the document?
> 
> For toc, you can already adjust its position in most of the
> templates.  You can't put it in an arbitrary position in the
> middle of the document body, but I don't see why that would
> be wanted.

The ability to place the TOC allows to put it after the copyright page
(without any special field), the dedication or even the epigraph. Or at
the end of the document, but before the colophon.

I have seen this in printed books and you probably too. TOC doesn’t have
a fixed place in the front or back matter. I think (and I hope) this is
a reasonable request.

About templates, some issues:

Why is the issue with the TOC different from bibliographies location
feature?

Handling templates is too hard for the newcomer. (I’m only trying to
explain the way superior quality of pandoc to basic computer users.)

Even for people that can handle templates, the problem is that each
different position in front or backmatter would require a different
template.

I think a basic capability would be to be able to place all
automatically-generated content from pandoc in the document. And I don’t
mean placing them in the middle of the body matter. TOC and footnotes
the same way as bibliographies may be placed.

I mean only placement, no formatting or another way of handling content.
Am I asking too much or am I deeply misguided?

> Footnotes are harder, because they're handled automatically
> in most formats.

Not in ePub. This is important. And probably in Word/LibreOffice they
could be placed as endnotes.

The issue is the following with ePub. With any other format that
supports endnotes you have a single reference (the number) for each
footnote.

With ePub either you write a document within a single XHTML file or
footnote numbers would be related to chapters.

If pandoc allows one source to rule them all: why not being able to
(optionally) place all footnotes at a user-given point?

Otherwise, high-quality PDF and ePub files would have different footnote
numbers when not reseting counters at each text division.

Sorry for the lengthy message, but I think this is a basic feature and I
would like to understand what is the problem with it.

Many thanks for your help,


Pablo
-- 
http://www.ousia.tk

-- 
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/564A2B6A.4060300%40web.de.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[BP Jonsson]

[-- Attachment #1: Type: text/plain, Size: 5111 bytes --]

You don't need a different template to place e.g. the TOC in different
places, only a new variable:

Somewhat simplified:

  $if(toc-in-backmatter)$
  $else$
  $toc$
  $endif$

  $body$

  $if(toc-in-backmatter)$
  $toc$
  $endif$

/bpj

måndag 16 november 2015 skrev Pablo Rodríguez <oinos-S0/GAf8tV78@public.gmane.org>:

> On 11/16/2015 02:51 AM, John MacFarlane wrote:
> > +++ Pablo Rodríguez [Nov 16 15 01:08 ]:
> >> [...]
> >> Would it be possible that pandoc automatically-generated contents could
> >> be placed by the user anywhere in the document?
> >
> > For toc, you can already adjust its position in most of the
> > templates.  You can't put it in an arbitrary position in the
> > middle of the document body, but I don't see why that would
> > be wanted.
>
> The ability to place the TOC allows to put it after the copyright page
> (without any special field), the dedication or even the epigraph. Or at
> the end of the document, but before the colophon.
>
> I have seen this in printed books and you probably too. TOC doesn’t have
> a fixed place in the front or back matter. I think (and I hope) this is
> a reasonable request.
>
> About templates, some issues:
>
> Why is the issue with the TOC different from bibliographies location
> feature?
>
> Handling templates is too hard for the newcomer. (I’m only trying to
> explain the way superior quality of pandoc to basic computer users.)
>
> Even for people that can handle templates, the problem is that each
> different position in front or backmatter would require a different
> template.
>
> I think a basic capability would be to be able to place all
> automatically-generated content from pandoc in the document. And I don’t
> mean placing them in the middle of the body matter. TOC and footnotes
> the same way as bibliographies may be placed.
>
> I mean only placement, no formatting or another way of handling content.
> Am I asking too much or am I deeply misguided?
>
> > Footnotes are harder, because they're handled automatically
> > in most formats.
>
> Not in ePub. This is important. And probably in Word/LibreOffice they
> could be placed as endnotes.
>
> The issue is the following with ePub. With any other format that
> supports endnotes you have a single reference (the number) for each
> footnote.
>
> With ePub either you write a document within a single XHTML file or
> footnote numbers would be related to chapters.
>
> If pandoc allows one source to rule them all: why not being able to
> (optionally) place all footnotes at a user-given point?
>
> Otherwise, high-quality PDF and ePub files would have different footnote
> numbers when not reseting counters at each text division.
>
> Sorry for the lengthy message, but I think this is a basic feature and I
> would like to understand what is the problem with it.
>
> Many thanks for your help,
>
>
> Pablo
> --
> http://www.ousia.tk
>
> --
> 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-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:;>.
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
> <javascript:;>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/564A2B6A.4060300%40web.de
> .
> For more options, visit https://groups.google.com/d/optout.
>


-- 

------------------------------
SavedURI :Show URLShow URLSavedURI :
SavedURI :Hide URLHide URLSavedURI :
https://mail.google.com/_/scs/mail-static/_/js/k=gmail.main.sv.G3GZFwvcniQ.O/m=m_i,t,it/am=fUAcTAoZawdGHAZ2YD-g9N_f7LL4CX7WlSgHQKgABHaCv9kToPiBD8qOMw/rt=h/d=1/rs=AItRSTO5CF1YB_frDRXLXTeUsQ1zItcBvwhttps://mail.google.com/_/scs/mail-static/_/js/k=gmail.main.sv.G3GZFwvcniQ.O/m=m_i,t,it/am=fUAcTAoZawdGHAZ2YD-g9N_f7LL4CX7WlSgHQKgABHaCv9kToPiBD8qOMw/rt=h/d=1/rs=AItRSTO5CF1YB_frDRXLXTeUsQ1zItcBvw
<https://mail.google.com/_/scs/mail-static/_/js/k=gmail.main.sv.G3GZFwvcniQ.O/m=m_i,t,it/am=fUAcTAoZawdGHAZ2YD-g9N_f7LL4CX7WlSgHQKgABHaCv9kToPiBD8qOMw/rt=h/d=1/rs=AItRSTO5CF1YB_frDRXLXTeUsQ1zItcBvw>
<https://mail.google.com/_/scs/mail-static/_/js/k=gmail.main.sv.G3GZFwvcniQ.O/m=m_i,t,it/am=fUAcTAoZawdGHAZ2YD-g9N_f7LL4CX7WlSgHQKgABHaCv9kToPiBD8qOMw/rt=h/d=1/rs=AItRSTO5CF1YB_frDRXLXTeUsQ1zItcBvw>
------------------------------

-- 
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/CAFC_yuTepqauzQ%2BuFqd4s6fr0CNCXk7%2B%2BNN-BQumuOnWQGnKwQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 6830 bytes --]

Re: ANN: pandoc 1.15.2

[John MACFARLANE]

I can understand how it's easier for users if they don't
have to mess with templates.  However, there are lots of
reasons why footnotes and tocs are difficult to treat in the
same way as the bibliography.  The bibliography was always part
of the document body (since it was just added to the end
of this by pandoc-citeproc).  We were able to change things
so that it can be added to an arbitrary div in the body.
But the toc, in many output formats, is not part of the
body text; it is specified in the header or preamble.
For example, in asciidoc, a `:toc:` attribute needs to be
included in the header.  In EPUB, the TOC belongs to a
special "guide" node.

With footnotes, the problem is that in many formats they're
generated automatically and can't be placed in arbitrary
places.

It ought to be possible to support a relocatable toc
element (`<div id="toc"></div>` as with refs).
In formats that don't allow this, like asciidoc,
we could just ignore this div.  But it would be a much
larger change than we did with bibliographies, since
a lot of the toc-generating code that is currently in
templates would have to be moved to the writers.
A by-product would be that less customization of
the appearance of tocs is possible (currently you can often
adjust the code that generates the toc in the template).
So I don't know if it's a good idea.

As BP points out, it's already possible to move TOCs around
in the front matter or back matter -- you just can't
position them in the body.

+++ Pablo Rodríguez [Nov 16 15 20:15 ]:
>On 11/16/2015 02:51 AM, John MacFarlane wrote:
>> +++ Pablo Rodríguez [Nov 16 15 01:08 ]:
>>> [...]
>>> Would it be possible that pandoc automatically-generated contents could
>>> be placed by the user anywhere in the document?
>>
>> For toc, you can already adjust its position in most of the
>> templates.  You can't put it in an arbitrary position in the
>> middle of the document body, but I don't see why that would
>> be wanted.
>
>The ability to place the TOC allows to put it after the copyright page
>(without any special field), the dedication or even the epigraph. Or at
>the end of the document, but before the colophon.
>
>I have seen this in printed books and you probably too. TOC doesn’t have
>a fixed place in the front or back matter. I think (and I hope) this is
>a reasonable request.
>
>About templates, some issues:
>
>Why is the issue with the TOC different from bibliographies location
>feature?
>
>Handling templates is too hard for the newcomer. (I’m only trying to
>explain the way superior quality of pandoc to basic computer users.)
>
>Even for people that can handle templates, the problem is that each
>different position in front or backmatter would require a different
>template.
>
>I think a basic capability would be to be able to place all
>automatically-generated content from pandoc in the document. And I don’t
>mean placing them in the middle of the body matter. TOC and footnotes
>the same way as bibliographies may be placed.
>
>I mean only placement, no formatting or another way of handling content.
>Am I asking too much or am I deeply misguided?
>
>> Footnotes are harder, because they're handled automatically
>> in most formats.
>
>Not in ePub. This is important. And probably in Word/LibreOffice they
>could be placed as endnotes.
>
>The issue is the following with ePub. With any other format that
>supports endnotes you have a single reference (the number) for each
>footnote.
>
>With ePub either you write a document within a single XHTML file or
>footnote numbers would be related to chapters.
>
>If pandoc allows one source to rule them all: why not being able to
>(optionally) place all footnotes at a user-given point?
>
>Otherwise, high-quality PDF and ePub files would have different footnote
>numbers when not reseting counters at each text division.
>
>Sorry for the lengthy message, but I think this is a basic feature and I
>would like to understand what is the problem with it.
>
>Many thanks for your help,
>
>
>Pablo
>-- 
>http://www.ousia.tk
>
>-- 
>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/564A2B6A.4060300%40web.de.
>For more options, visit https://groups.google.com/d/optout.

-- 
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/20151117191207.GA69521%40protagoras.berkeley.edu.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[Pablo Rodríguez]

On 11/17/2015 08:12 PM, John MACFARLANE wrote:
> I can understand how it's easier for users if they don't
> have to mess with templates.  However, there are lots of
> reasons why footnotes and tocs are difficult to treat in the
> same way as the bibliography.  The bibliography was always part
> of the document body (since it was just added to the end
> of this by pandoc-citeproc).  We were able to change things
> so that it can be added to an arbitrary div in the body.
> But the toc, in many output formats, is not part of the
> body text; it is specified in the header or preamble.
> For example, in asciidoc, a `:toc:` attribute needs to be
> included in the header.  In EPUB, the TOC belongs to a
> special "guide" node.

Not in ePub 2, as far as I know.

And which is the problem of the guide node in ePub 3? TOCs may be placed
at everywere in the document, according to
https://github.com/IDPF/epub3-samples/blob/master/30/moby-dick/OPS/package.opf.

> With footnotes, the problem is that in many formats they're
> generated automatically and can't be placed in arbitrary
> places.

In that cases, footnote placing could be simply ignored.

But how about in ePub? LaTeX and ConTeXt can place endnotes too.

> It ought to be possible to support a relocatable toc
> element (`<div id="toc"></div>` as with refs).
> In formats that don't allow this, like asciidoc,
> we could just ignore this div.  But it would be a much
> larger change than we did with bibliographies, since
> a lot of the toc-generating code that is currently in
> templates would have to be moved to the writers.
> A by-product would be that less customization of
> the appearance of tocs is possible (currently you can often
> adjust the code that generates the toc in the template).
> So I don't know if it's a good idea.

Why less customization? No elements and attributes for the TOC? This is
all whe need for customizing format, isn’t it?

> As BP points out, it's already possible to move TOCs around
> in the front matter or back matter -- you just can't
> position them in the body.

Sorry, but this fix needs templating. I don’t use TOCs myself in ePub,
since I cannot place them in the Markdown source.

I’m trying to explain pandoc to other people. Templates are out of our
scope (they are average users, not computer experts).

My explanation to them is that TOC position is hard coded.

Many thanks for your help,


Pablo
-- 
http://www.ousia.tk

-- 
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/564E1C35.9060202%40web.de.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[Pablo Rodríguez]

On 11/17/2015 12:31 PM, BP Jonsson wrote:
> You don't need a different template to place e.g. the TOC in different
> places, only a new variable:
> 
> Somewhat simplified:
> 
>   $if(toc-in-backmatter)$
>   $else$
>   $toc$
>   $endif$
>   
>   $body$
>   
>   $if(toc-in-backmatter)$
>   $toc$
>   $endif$

Many thanks for your help, BPJ.

I’m afraid that this is more complex (or I’m way more [unnecessarily]
complicated ;-)).

I want to place the TOC after the copyright page, the dedication and the
epigraph and before the foreword (if any) or introduction.

But sometimes, I need to place it at the end of the document, but before
the colophon.

All that I have described, this is body matter for pandoc. In a real
book they are front and back matters.

I know this could be achieved with pandoc with variables and special
templating. The source document itsel becomes much less readable. But I
want a portable solution and I need to be able to write chapters as the
chapters they are.

A friend I’m trying to convince to move to pandoc instead of a word
processor told me once that she didn’t get the what she saw as an
inconsistency in pandoc.

Her background is in humanities and she’s a high school teacher
(incredibly intelligent person, but not a hacker or even specially
interested in computers or software as such).

pandoc has a whole bibliography system and a whole math mode (I told her
about those, but I haven’t explained them, since I haven’t used them
myself). And she acknowledges that those are great features. But it is
rather weird that you cannot place the TOC.

Going back to myself, I must confess that I’m too biased by TeX. I
expect from pandoc, that two generic commands that read something like:

    \tableofcontentscomeshere

    \documentnotescomehere

I think that pandoc is great. Because of that, I don’t get why it
doesn’t implement this basic feature.

Sorry if I’m too demanding. I’m speaking from the user’s perspective,
from the need of using it.

Many thanks for your help,


Pablo
-- 
http://www.ousia.tk

-- 
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/564E20D8.5000509%40web.de.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[John MACFARLANE]

+++ Pablo Rodríguez [Nov 19 15 20:19 ]:
>On 11/17/2015 12:31 PM, BP Jonsson wrote:
>> You don't need a different template to place e.g. the TOC in different
>> places, only a new variable:
>>
>> Somewhat simplified:
>>
>>   $if(toc-in-backmatter)$
>>   $else$
>>   $toc$
>>   $endif$
>>
>>   $body$
>>
>>   $if(toc-in-backmatter)$
>>   $toc$
>>   $endif$
>
>Many thanks for your help, BPJ.
>
>I’m afraid that this is more complex (or I’m way more [unnecessarily]
>complicated ;-)).
>
>I want to place the TOC after the copyright page, the dedication and the
>epigraph and before the foreword (if any) or introduction.
>
>But sometimes, I need to place it at the end of the document, but before
>the colophon.
>
>All that I have described, this is body matter for pandoc. In a real
>book they are front and back matters.

What I would do is put the text of the dedication and
epigraph in metadata variables:

...
dedication: |
  Thanks to...
epigraph: |
  Blah blah.
---

Then, in your template, handle these as front matter.
How you handle them will vary from one output format to
another.  (LaTeX has a special epigraph environment,
for example.)

Put the toc after these in your template.  Problem solved.

Yes, it involves mucking with the template.  But that is
really necessary in this case, if you want nice-looking
output, because the best way to handle dedications and
epigraphs is different in different output formats.

-- 
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/20151119203204.GA2192%40protagoras.berkeley.edu.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[BP Jonsson]

Den 2015-11-19 kl. 21:32, skrev John MACFARLANE:
>
> ...
> dedication: |
>   Thanks to...
> epigraph: |
>   Blah blah.
> ---


Just for future newbies: you got the --- and ... lines swapped there.

Re: ANN: pandoc 1.15.2

[BP Jonsson]

Den 2015-11-19 kl. 21:32, skrev John MACFARLANE:
> What I would do is put the text of the dedication and
> epigraph in metadata variables:
>
> ...
> dedication: |
>   Thanks to...
> epigraph: |
>   Blah blah.
> ---
>
> Then, in your template, handle these as front matter.
> How you handle them will vary from one output format to
> another.  (LaTeX has a special epigraph environment,
> for example.)
>
> Put the toc after these in your template.  Problem solved.

@Pablo note that you can have several metadata blocks anywhere in 
your document, so you could have those variables which should go 
in the backmatter at the end if you like.

I have been using the method John describes for abstracts for some 
time, and I mostly put the abstract in its own metadata block 
after the title/author/date, and formatting variables in a block 
at the end of the document. Not strictly necessary but clearer to 
a reader unfamiliar with the format and probably uninterested in 
the formatting variables.
Also or alternatively you may separate things in a metadata block 
with blank lines.

Here is an example. The only things which might look *really* 
strange to an 'uninitiated' reader are the YAML block indicators 
after the 'abstract:' and 'epigraph:' keys:

     ---
     title:  Maiores officia et nemo
     author: Magnam Laudantium
     date:   20 November 2015
     ...

     ---
     abstract: |
         Ut modi soluta minus esse inventore enim
         atque eum. Veniam hic qui qui soluta
         quis. Quia vel aperiam praesentium.


     epigraph: |
         *Vel nihil aut rerum laboriosam.*
     ...

     Commodi ea facilis ab.... <!-- body -->

     ---
     mainfont: Eaque Dolor
     ...

That doesn't look too bad, does it?

The snag is that *if* you reformat the document with pandoc 
everything is mashed into a single compact metadata block. One 
workaround is to put HTML comments around those metadata blocks 
during the editing/reformatting cycle.  Another way to keep a 
modicum of organization in a single metadata block is to make it 
hierarchical, which is both easier toread and easier to reorganize 
after reformatting if you need to share :

     ---
     frontmatter:
         abstract: |
             Ut modi soluta minus esse inventore enim
             atque eum. Veniam hic qui qui soluta
             quis. Quia vel aperiam praesentium.
         epigraph: |
             *Vel nihil aut rerum laboriosam.*
     ...

and then in your template:

     <div id="abstract">
     $frontmatter.abstract$
     </div>

If you are daring you may even replace 'standard' variables which 
are user defined like `$title$` with e.g. `$document.title$`. The 
downside to that is that you can't set such variables from the 
command line, but that can be worked around also if actually needed:

     $if(title)$
     $if(document.subtitle)$
     \title{$title$\\\vspace{0.5em}{\large $document.subtitle$}}
     $else$
     \title{$title$$if(subtitle)$\\\vspace{0.5em}{\large 
$subtitle$}$endif$}
     $endif$
     $else$
     $if(document.title)$
 
\title{$document.title$$if(document.subtitle)$\\\vspace{0.5em}{\large
         $document.subtitle$}$endif$}
     $endif$
     $endif$
     $if(author)$
     \author{$for(author)$$author$$sep$ \and $endfor$}
     $else$
     $if(document.author)$
     \author{$for(document.author)$$document.author$$sep$ \and 
$endfor$}
     $endif$
     $endif$
     $if(document.date)$
     \date{$document.date$}
     $else$
     \date{$date$}
     $endif$

BTW if your template gets hard to navigate there is a trick to put 
'comments' which won't be visible in the output:

     $if(templatecomment)$
     **** This is a comment with asterisks to make it stand out ****
     $endif$

and never setting the 'templatecomment' variable to a true value! 
The only thing left around will be a blank line, which hopefully 
makes the preamble or `<head>>` more readable.

/bpj

Re: ANN: pandoc 1.15.2

[Pablo Rodríguez]

On 11/19/2015 09:32 PM, John MACFARLANE wrote:
> +++ Pablo Rodríguez [Nov 19 15 20:19 ]:
>> [...
]>> But sometimes, I need to place it at the end of the document, but before
>> the colophon.
>>
>> All that I have described, this is body matter for pandoc. In a real
>> book they are front and back matters.
> 
> What I would do is put the text of the dedication and
> epigraph in metadata variables:
> 
> ...
> dedication: |
>   Thanks to...
> epigraph: |
>   Blah blah.
> ---
> 
> Then, in your template, handle these as front matter.
> How you handle them will vary from one output format to
> another.  (LaTeX has a special epigraph environment,
> for example.)
> 
> Put the toc after these in your template.  Problem solved.

I knew that it was possible. This is the same case as in the copyright
before the TOC.

Too complex for the average user. Explaining pandoc requires explaining
or writing templates for new users.

> Yes, it involves mucking with the template.  But that is
> really necessary in this case, if you want nice-looking
> output, because the best way to handle dedications and
> epigraphs is different in different output formats.

Would it be a way to place footnotes in a single chapter when generating
an ePub file? I mean, also using templates.

Many thanks for your help,


Pablo
-- 
http://www.ousia.tk

-- 
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/5651FEEA.7000100%40web.de.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[Pablo Rodríguez]

On 11/20/2015 07:38 PM, BP Jonsson wrote:
> Den 2015-11-19 kl. 21:32, skrev John MACFARLANE:
>> What I would do is put the text of the dedication and
>> epigraph in metadata variables:
>>
>> ...
>> dedication: |
>>   Thanks to...
>> epigraph: |
>>   Blah blah.
>> ---
>>
>> Then, in your template, handle these as front matter.
>> How you handle them will vary from one output format to
>> another.  (LaTeX has a special epigraph environment,
>> for example.)
>>
>> Put the toc after these in your template.  Problem solved.
> 
> @Pablo note that you can have several metadata blocks anywhere in 
> your document, so you could have those variables which should go 
> in the backmatter at the end if you like.

Mixing markup styles is not the ideal improvement of HTML that Markdown
is supposed to simplify. But well...

> Here is an example. The only things which might look *really* 
> strange to an 'uninitiated' reader are the YAML block indicators 
> after the 'abstract:' and 'epigraph:' keys:
> 
>      ---
>      title:  Maiores officia et nemo
>      author: Magnam Laudantium
>      date:   20 November 2015
>      ...
> 
>      ---
>      abstract: |
>          Ut modi soluta minus esse inventore enim
>          atque eum. Veniam hic qui qui soluta
>          quis. Quia vel aperiam praesentium.
> 
> 
>      epigraph: |
>          *Vel nihil aut rerum laboriosam.*
>      ...
> 
>      Commodi ea facilis ab.... <!-- body -->
> 
>      ---
>      mainfont: Eaque Dolor
>      ...
> 
> That doesn't look too bad, does it?

Sorry, but it looks crazy. Mixing standard Markdown with YAML snippets
may lead to accidental syntax mistakes when typing text.

As a personal note. I have been using ConTeXt for over five years now.
I’m moving some of my documents to Markdown. And sometimes I markup
emphasis or footnotes in ConTeXt as if it were Markdown. I may not be
the exception there.

Not to mention which possible explanation (a really good one) could not
scare anyone learning Markdown.

> The snag is that *if* you reformat the document with pandoc 
> everything is mashed into a single compact metadata block. One 
> workaround is to put HTML comments around those metadata blocks 
> during the editing/reformatting cycle.  Another way to keep a 
> modicum of organization in a single metadata block is to make it 
> hierarchical, which is both easier toread and easier to reorganize 
> after reformatting if you need to share :
> 
>      ---
>      frontmatter:
>          abstract: |
>              Ut modi soluta minus esse inventore enim
>              atque eum. Veniam hic qui qui soluta
>              quis. Quia vel aperiam praesentium.
>          epigraph: |
>              *Vel nihil aut rerum laboriosam.*
>      ...
> 
> and then in your template:
> 
>      <div id="abstract">
>      $frontmatter.abstract$
>      </div>

Keeping things simple is a good way of avoiding problems (at least for
my simple mind).

Sorry, but I see no real gain in making text-content variables hierarchical.

Many thanks for your help,


Pablo
-- 
http://www.ousia.tk

-- 
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/56521ECE.1000504%40web.de.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[BP Jonsson]

Den 2015-11-22 kl. 18:44, skrev Pablo Rodríguez:
> Too complex for the average user. Explaining pandoc requires explaining
> or writing templates for new users.

It is hard to tell what functionality new users will want. Assumptions
that "everybody will want the same missing features as I want" or
"nobody uses that feature (which I don't use)" are usually wrong; 
it is
rather the case that each user uses only around 20% percent of the
functionality but different users use a different 20% of the whole
feature set, and likewise only a certain percentage of all actual or
potential users will miss any possible feature. When writing 
software it
is not a good idea to include features which someone *might* want 
ahead
of actually knowing that that someone exists, or you will end up 
with MS
Word before you know it. It is much better to include
customization/plugin support, as pandoc does with filters and 
templates.
Alas it is often the case that software offers customization
possibilities which only 20% of users use! :-)

If you feel that templates with variables for controlling what 'fixed
parts' go where, or something else which can be controlled with a
template, would be worth having *for yourself* then writing those
templates and publishing them on GitHub is worthwhile. Suddenly 
some day
someone will star, follow or fork your repo. If you are going to write
an introduction to pandoc you can link to that repo and explain how
to use those control variables, and then perhaps include an appendix
about modifying templates (not writing them from scratch!) I have 
myself
considered to write an introduction to pandoc and markdown, in 
Swedish,
and to publish templates aimed at Swedish users along with it.[^1]

After all what use is a template system if nobody dares to
write/modify/publish their own templates?[^2] It would be good if
templates had a comment syntax of their own so that the standard
templates could include explanations of what the different parts,
especially conditionally/alternatively included parts and 
variables are
for which don't show up in the output. That would make the entry into
creating, publishing and using custom templates much easier. While
commenting out by dummy conditional works it is not ideal: one day
someone *will* set that variable to true and havoc will ensue!

[^1]: Such templates would have the extra complication that Swedish
     users can be expected to want to write documents sometimes in
     Swedish and sometimes in English, so there would need to be a
     variable for that, so that people who so wish can use those
     templates as their default templates. What holds me back -- apart
     from lack of time -- is that I only use some of the different
     formats pandoc supports. Of course I should follow my own 
advice and
     start with those formats which I use!

[^2]: Of course the same is true of filters. The main stumbling 
block is
     probably that if you want your templates or filters to be 
useful for
     others you must write documentation for them. Documentation often
     takes more time to write and more storage space than the thing
     itself!

-- 
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/56522E1E.9020601%40gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: ANN: pandoc 1.15.2

[John MacFarlane]

+++ BP Jonsson [Nov 22 15 22:05 ]:
> It would be good if
>templates had a comment syntax of their own so that the standard
>templates could include explanations of what the different parts,
>especially conditionally/alternatively included parts and variables 
>are
>for which don't show up in the output. That would make the entry into
>creating, publishing and using custom templates much easier. While
>commenting out by dummy conditional works it is not ideal: one day
>someone *will* set that variable to true and havoc will ensue!

This could be added - put something on issues?

As long as the syntax started with $, it wouldn't interfere
with anything, since literal $'s need to be escaped as $$
in templates.  So, for example, a comment could be a line
beginning

$--

or

$:

Or something like

$comment$
My comment.
$endcomment$

Re: ANN: pandoc 1.15.2

[david.pw.smith-Re5JQEeQqe8AvxtiuMwx3w]

[-- Attachment #1.1: Type: text/plain, Size: 3174 bytes --]



On Thursday, 19 November 2015 19:19:55 UTC, ousia wrote:

>
> A friend I’m trying to convince to move to pandoc instead of a word 
> processor told me once that she didn’t get the what she saw as an 
> inconsistency in pandoc. 
>
> Her background is in humanities and she’s a high school teacher 
> (incredibly intelligent person, but not a hacker or even specially 
> interested in computers or software as such). 
>
> pandoc has a whole bibliography system and a whole math mode (I told her 
> about those, but I haven’t explained them, since I haven’t used them 
> myself). And she acknowledges that those are great features. But it is 
> rather weird that you cannot place the TOC. 
>

I have to ask -- and this might not be a popular question/opinion I 
suppose, and perhaps not in the scope of the thread here, but it's 
something I think is worth bearing in mind with any software change or 
development or architecture or whatever: *why* are you trying to convince 
someone to move from a tool which they already know how to use to one which 
has a steep learning curve and requires extra work to do what they want it 
to? As someone from a humanities background who uses pandoc, I think it's 
great for typesetting professional-looking academic papers, but that's 
about all it's great for. The maths functions are largely irrelevant, 
however excellent they might be. The bibliography function is useful, but 
no more so than zotero's integration with word. Close to 100% of academic 
journals in the humanities demand submissions in word format, and it's 
great that pandoc can convert Markdown to Word if markdown is what you 
already use, but it can be spotty, and it's definitely worse at outputting 
word files than... Word.

Developers of software must always be careful to make sure (as has been 
noted in this thread already) that features they build relate to specific, 
real user needs. If you are trying to help someone change the software they 
use then you must have the same consideration. Having written a few howto's 
about my pandoc setup for academic writing, the most frequent response I am 
compelled by my conscience to give to anyone who has trouble getting to 
grips with pandoc (most frequently in the form of "I want to use pandoc to 
write my thesis/dissertation/paper but can you just explain it a bit better 
for a less technical user...") is: for heaven's sake don't make extra work 
for yourself by using unfamiliar tools to do a job which is already hard 
enough on its own.

Sorry. Rant over!

-- 
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/177624fd-99f7-4ff2-b7d9-36941644a82a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 3755 bytes --]

Re: ANN: pandoc 1.15.2

[Jason White]

Pablo Rodríguez <oinos-S0/GAf8tV78@public.gmane.org> wrote:
 
> I knew that it was possible. This is the same case as in the copyright
> before the TOC.
> 
> Too complex for the average user. Explaining pandoc requires explaining
> or writing templates for new users.


Templates aren't complicated, but you need to understand the output format in
order to customize it.

I think it's best to come to Pandoc after having understood LaTeX, HTML or
whatever other output format you rely on most.

If a document is destined primarily for printing or viewing on screen, I would
use LaTeX directly, or write in Markdown and then convert to LaTeX with
Pandoc, then edit the material further in LaTeX.

These tools are well suited to average users who want to learn and thereby
become better than average; but for those who aren't motivated to learn the
technical details, there are other solutions on offer such as word processors.

-- 
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/20151124010251.GA24244%40jpc.jasonjgw.net.
For more options, visit https://groups.google.com/d/optout.