Announcing the pandoc acronym filter

Announcing the pandoc acronym filter

[Mirko Boehm (KDE)]

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

Hello there,

for a recent article I needed a way to automatically expand acronyms on the first use. Since there was not a good solution for it, I implemented a pandoc filter that does the trick. You can find it here: https://gitlab.com/mirkoboehm/pandoc-acronyms <https://gitlab.com/mirkoboehm/pandoc-acronyms> It is distributed via pip: https://pypi.org/project/pandoc-acronyms/ <https://pypi.org/project/pandoc-acronyms/> Once installed, it runs as a stand-alone program in the usual pandoc filter way.

Can I ask for some feedback? There are a couple of things to discuss:
The syntax: Acronyms are marked like this: [!bba]. Does that clash with other naming schemes? It it sound?
I would like to add a feature to generate an acronym index at a marked location in the document. What would be the best way to do that?

To suggest improvements, feel free to add them as issues to the Gitlab project so that they don’t get lost in the discussion thread.

Best,

Mirko.
-- 
Mirko Boehm | mirko-RoXCvvDuEio@public.gmane.org | KDE e.V.
Qt Certified Specialist and Trainer
Request a meeting: https://doodle.com/mirkoboehm

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/DBA1070B-849F-45B3-81CA-ECA9100C32F9%40kde.org.

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

Re: Announcing the pandoc acronym filter

[Benct Philip Jonsson]

On 2020-02-06 12:47, Mirko Boehm (KDE) wrote:
> Hello there,
> 
> for a recent article I needed a way to automatically expand acronyms on the first use. Since there was not a good solution for it, I implemented a pandoc filter that does the trick. You can find it here: https://gitlab.com/mirkoboehm/pandoc-acronyms <https://gitlab.com/mirkoboehm/pandoc-acronyms> It is distributed via pip: https://pypi.org/project/pandoc-acronyms/ <https://pypi.org/project/pandoc-acronyms/> Once installed, it runs as a stand-alone program in the usual pandoc filter way.
> 
> Can I ask for some feedback? There are a couple of things to discuss:
> The syntax: Acronyms are marked like this: [!bba]. Does that clash with other naming schemes? It it sound?

It is probably more robust to use a span with a class and then look for 
spans with that class: `[bba]{.a}`.  You may want to use a longer class 
name but a single letter is less to type.

> I would like to add a feature to generate an acronym index at a marked location in the document. What would be the best way to do that?

Mark the spot with a div or heading with a certain class.  Then make one 
pass to collect the acronyms and another to insert the index.

> 
> To suggest improvements, feel free to add them as issues to the Gitlab project so that they don’t get lost in the discussion thread.
> 
> Best,
> 
> Mirko.
> 

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/afbd510c-bccb-07d1-6c90-e141563c87b6%40gmail.com.

Re: Announcing the pandoc acronym filter

[Albert Krewinkel]

Hi,

this looks like a nice and useful filter!

Mirko Boehm (KDE) writes:

> Can I ask for some feedback? There are a couple of things to discuss:
> The syntax: Acronyms are marked like this: [!bba]. Does that clash
> with other naming schemes? It it sound?

Looks good to me. Just using uppercase text like "BBA" could also
work and would be easier on the eyes – also depends on how
noticeable you want acronyms to be in your source.

Don't forget to add your filter to the wiki on GitHub so others
can find it: <https://github.com/jgm/pandoc/wiki/Pandoc-Filters>

Cheers,
-Albert

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/87eev7h04j.fsf%40zeitkraut.de.

Re: Announcing the pandoc acronym filter

[Mirko Boehm]

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

Thanks for the comments!

On Thursday, February 6, 2020 at 6:04:14 PM UTC+1, BP wrote:
>
> On 2020-02-06 12:47, Mirko Boehm (KDE) wrote: 
> > Hello there, 
> > 
> > for a recent article I needed a way to automatically expand acronyms on 
> the first use. Since there was not a good solution for it, I implemented a 
> pandoc filter that does the trick. You can find it here: 
> https://gitlab.com/mirkoboehm/pandoc-acronyms <
> https://gitlab.com/mirkoboehm/pandoc-acronyms> It is distributed via pip: 
> https://pypi.org/project/pandoc-acronyms/ <
> https://pypi.org/project/pandoc-acronyms/> Once installed, it runs as a 
> stand-alone program in the usual pandoc filter way. 
> > 
> > Can I ask for some feedback? There are a couple of things to discuss: 
> > The syntax: Acronyms are marked like this: [!bba]. Does that clash with 
> other naming schemes? It it sound? 
>
> It is probably more robust to use a span with a class and then look for 
> spans with that class: `[bba]{.a}`.  You may want to use a longer class 
> name but a single letter is less to type. 
>

Not sure I understand. The current concept is: The original document 
contains [!bba]. This is the marker [!...] that contains the key "bba" of 
the acronym. It is replaced with the acronym ("BBA") or the full text on 
first use ("beer brewing attitude (BBA)"). Could you elaborate how this 
relates to the [bba] and the {.a} parts in your example?

BTW, the syntax is made to be similar to citations ("[@author1999]").

>
> > I would like to add a feature to generate an acronym index at a marked 
> location in the document. What would be the best way to do that? 
>
> Mark the spot with a div or heading with a certain class.  Then make one 
> pass to collect the acronyms and another to insert the index. 
>

A heading would be something like "# Acronyms"? I am not sure I fully 
understand the use of classes. Is there a source where I can read up on it?

All the best,

Mirko.

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/4e94a11f-3e3d-4ebb-b047-94e61110fd98%40googlegroups.com.

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

Re: Announcing the pandoc acronym filter

[Mirko Boehm]

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

Hi!

On Thursday, February 6, 2020 at 10:33:24 PM UTC+1, Albert Krewinkel wrote:
>
> Hi, 
>
> this looks like a nice and useful filter! 
>
> Mirko Boehm (KDE) writes: 
>
> > Can I ask for some feedback? There are a couple of things to discuss: 
> > The syntax: Acronyms are marked like this: [!bba]. Does that clash 
> > with other naming schemes? It it sound? 
>
> Looks good to me. Just using uppercase text like "BBA" could also 
> work and would be easier on the eyes – also depends on how 
> noticeable you want acronyms to be in your source. 
>

I am thinking about this as "trivial mode". It runs the risk of replacing 
things that are not meant to be replaced. I am also working on a 
suggestions mode where the filter prints notices if it finds the short 
forms of acronyms not marked as one.
 

>
> Don't forget to add your filter to the wiki on GitHub so others 
> can find it: <https://github.com/jgm/pandoc/wiki/Pandoc-Filters> 
>

Done. Thanks!

Mirko.

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/566073a2-dd21-45b9-80c4-467d7d943679%40googlegroups.com.

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

Re: Announcing the pandoc acronym filter

[Patrick Hilhorst]

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

> The syntax: Acronyms are marked like this: [!bba]. Does that clash with 
other naming schemes? It it sound?

Might be nice to have it be configurable somehow. It is also the naming 
scheme I use for my personal pandoc template to generate labels and 
references (https://github.com/synthetica9/tufte-pandoc#custom-syntax). I 
don't think anyone else uses this template, so I might just change it in my 
template.

On Thursday, 6 February 2020 12:47:22 UTC+1, Mirko Boehm wrote:
>
> Hello there,
>
> for a recent article I needed a way to automatically expand acronyms on 
> the first use. Since there was not a good solution for it, I implemented a 
> pandoc filter that does the trick. You can find it here: 
> https://gitlab.com/mirkoboehm/pandoc-acronyms It is distributed via pip: 
> https://pypi.org/project/pandoc-acronyms/ Once installed, it runs as a 
> stand-alone program in the usual pandoc filter way.
>
> Can I ask for some feedback? There are a couple of things to discuss:
>
>    - The syntax: Acronyms are marked like this: [!bba]. Does that clash 
>    with other naming schemes? It it sound?
>    - I would like to add a feature to generate an acronym index at a 
>    marked location in the document. What would be the best way to do that?
>
>
> To suggest improvements, feel free to add them as issues to the Gitlab 
> project so that they don’t get lost in the discussion thread.
>
> Best,
>
> Mirko.
> -- 
> Mirko Boehm | mi...-RoXCvvDuEio@public.gmane.org <javascript:> | KDE e.V.
> Qt Certified Specialist and Trainer
> Request a meeting: https://doodle.com/mirkoboehm
>
>

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/795bf987-c198-4723-b1f0-16711603632b%40googlegroups.com.

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

Re: Announcing the pandoc acronym filter

[Mirko Boehm (KDE)]

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

Hi!

> On 7. Feb 2020, at 11:48, Patrick Hilhorst <patrickhilhorst97-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 
> > The syntax: Acronyms are marked like this: [!bba]. Does that clash with other naming schemes? It it sound?
> 
> Might be nice to have it be configurable somehow. It is also the naming scheme I use for my personal pandoc template to generate labels and references (https://github.com/synthetica9/tufte-pandoc#custom-syntax <https://github.com/synthetica9/tufte-pandoc#custom-syntax>). I don't think anyone else uses this template, so I might just change it in my template.

I was sure there would be an overlap with some existing solutions :-) I will see if this can be made configurable.

This also reminds me that the filter needs a “null statement” in case somebody wants to write [!text] without having it replaced.

Best,

Mirko.
-- 
Mirko Boehm | mirko-RoXCvvDuEio@public.gmane.org | KDE e.V.
Qt Certified Specialist and Trainer
Request a meeting: https://doodle.com/mirkoboehm

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/FD93CF69-7AC8-4D80-B383-B4BE8868FEC2%40kde.org.

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

Re: Announcing the pandoc acronym filter

[Corentin Dupont]

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

HI Mirko,
very nice idea!
I think it would be most useful if the filter could be applied to existing
texts and technical writing (with no modification).
I feel that asking the authors to write a separate data file and learn a
special syntax is overkill (maybe I'm lazy).

What would be nice is if the filter could detect/fix that you didn't
expand/define an acronym, or that you expanded it twice.
Do you think it's feasible?
Cheers
Corentin

On Thu, Feb 6, 2020 at 12:47 PM Mirko Boehm (KDE) <mirko-RoXCvvDuEio@public.gmane.org> wrote:

> Hello there,
>
> for a recent article I needed a way to automatically expand acronyms on
> the first use. Since there was not a good solution for it, I implemented a
> pandoc filter that does the trick. You can find it here:
> https://gitlab.com/mirkoboehm/pandoc-acronyms It is distributed via pip:
> https://pypi.org/project/pandoc-acronyms/ Once installed, it runs as a
> stand-alone program in the usual pandoc filter way.
>
> Can I ask for some feedback? There are a couple of things to discuss:
>
>    - The syntax: Acronyms are marked like this: [!bba]. Does that clash
>    with other naming schemes? It it sound?
>    - I would like to add a feature to generate an acronym index at a
>    marked location in the document. What would be the best way to do that?
>
>
> To suggest improvements, feel free to add them as issues to the Gitlab
> project so that they don’t get lost in the discussion thread.
>
> Best,
>
> Mirko.
> --
> Mirko Boehm | mirko-RoXCvvDuEio@public.gmane.org | KDE e.V.
> Qt Certified Specialist and Trainer
> Request a meeting: https://doodle.com/mirkoboehm
>
> --
> 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 view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/DBA1070B-849F-45B3-81CA-ECA9100C32F9%40kde.org
> <https://groups.google.com/d/msgid/pandoc-discuss/DBA1070B-849F-45B3-81CA-ECA9100C32F9%40kde.org?utm_medium=email&utm_source=footer>
> .
>

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAEyhvmqkmZs7k%3D_Y%3Drv%2BvFSHNiVhjRYgvuOG4Y7ZocqcgpaGmQ%40mail.gmail.com.

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

Re: Announcing the pandoc acronym filter

[BPJ]

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

Read about native/bracketed spans/divs and attributes in the very fine
Pandoc manual! Everything to make my suggestions clear is in there!

https://pandoc.org/MANUAL.html#divs-and-spans

Den fre 7 feb. 2020 11:20Mirko Boehm <mirko-RoXCvvDuEio@public.gmane.org> skrev:

> Thanks for the comments!
>
> On Thursday, February 6, 2020 at 6:04:14 PM UTC+1, BP wrote:
>>
>> On 2020-02-06 12:47, Mirko Boehm (KDE) wrote:
>> > Hello there,
>> >
>> > for a recent article I needed a way to automatically expand acronyms on
>> the first use. Since there was not a good solution for it, I implemented a
>> pandoc filter that does the trick. You can find it here:
>> https://gitlab.com/mirkoboehm/pandoc-acronyms <
>> https://gitlab.com/mirkoboehm/pandoc-acronyms> It is distributed via
>> pip: https://pypi.org/project/pandoc-acronyms/ <
>> https://pypi.org/project/pandoc-acronyms/> Once installed, it runs as a
>> stand-alone program in the usual pandoc filter way.
>> >
>> > Can I ask for some feedback? There are a couple of things to discuss:
>> > The syntax: Acronyms are marked like this: [!bba]. Does that clash with
>> other naming schemes? It it sound?
>>
>> It is probably more robust to use a span with a class and then look for
>> spans with that class: `[bba]{.a}`.  You may want to use a longer class
>> name but a single letter is less to type.
>>
>
> Not sure I understand. The current concept is: The original document
> contains [!bba]. This is the marker [!...] that contains the key "bba" of
> the acronym. It is replaced with the acronym ("BBA") or the full text on
> first use ("beer brewing attitude (BBA)"). Could you elaborate how this
> relates to the [bba] and the {.a} parts in your example?
>
> BTW, the syntax is made to be similar to citations ("[@author1999]").
>
>>
>> > I would like to add a feature to generate an acronym index at a marked
>> location in the document. What would be the best way to do that?
>>
>> Mark the spot with a div or heading with a certain class.  Then make one
>> pass to collect the acronyms and another to insert the index.
>>
>
> A heading would be something like "# Acronyms"? I am not sure I fully
> understand the use of classes. Is there a source where I can read up on it?
>
> All the best,
>
> Mirko.
>
> --
> 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 view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/4e94a11f-3e3d-4ebb-b047-94e61110fd98%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/4e94a11f-3e3d-4ebb-b047-94e61110fd98%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
>

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhDCpV7KhXZ%3DZb5uCfFbx4MCn5XJMOK6py2jxKJetCOXjw%40mail.gmail.com.

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

Re: Announcing the pandoc acronym filter

[Mirko Boehm]

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

Hi!

I have implemented a "--suggest" feature that prints notes if an unmarked 
acronym is found.

I am considering a mode of operation where acronyms don't need to be 
marked. It is difficult to be consistent with that, though. For example, 
how exactly would you know what the expanded text is? Still thinking about 
it.

The new version is released, see 
here: https://twitter.com/mirkoboehm/status/1230632105752875009

Best,

Mirko.

On Friday, February 7, 2020 at 5:03:55 PM UTC+1, Corentin Dupont wrote:
>
> HI Mirko,
> very nice idea!
> I think it would be most useful if the filter could be applied to existing 
> texts and technical writing (with no modification).
> I feel that asking the authors to write a separate data file and learn a 
> special syntax is overkill (maybe I'm lazy).
>
> What would be nice is if the filter could detect/fix that you didn't 
> expand/define an acronym, or that you expanded it twice.
> Do you think it's feasible?
> Cheers
> Corentin
>
> On Thu, Feb 6, 2020 at 12:47 PM Mirko Boehm (KDE) <mi...-RoXCvvDuEio@public.gmane.org 
> <javascript:>> wrote:
>
>> Hello there,
>>
>> for a recent article I needed a way to automatically expand acronyms on 
>> the first use. Since there was not a good solution for it, I implemented a 
>> pandoc filter that does the trick. You can find it here: 
>> https://gitlab.com/mirkoboehm/pandoc-acronyms It is distributed via pip: 
>> https://pypi.org/project/pandoc-acronyms/ Once installed, it runs as a 
>> stand-alone program in the usual pandoc filter way.
>>
>> Can I ask for some feedback? There are a couple of things to discuss:
>>
>>    - The syntax: Acronyms are marked like this: [!bba]. Does that clash 
>>    with other naming schemes? It it sound?
>>    - I would like to add a feature to generate an acronym index at a 
>>    marked location in the document. What would be the best way to do that?
>>
>>
>> To suggest improvements, feel free to add them as issues to the Gitlab 
>> project so that they don’t get lost in the discussion thread.
>>
>> Best,
>>
>> Mirko.
>> -- 
>> Mirko Boehm | mi...-RoXCvvDuEio@public.gmane.org <javascript:> | KDE e.V.
>> Qt Certified Specialist and Trainer
>> Request a meeting: https://doodle.com/mirkoboehm
>>
>> -- 
>> 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-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>.
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/pandoc-discuss/DBA1070B-849F-45B3-81CA-ECA9100C32F9%40kde.org 
>> <https://groups.google.com/d/msgid/pandoc-discuss/DBA1070B-849F-45B3-81CA-ECA9100C32F9%40kde.org?utm_medium=email&utm_source=footer>
>> .
>>
>

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/cea0c10c-1cfb-40d7-a464-cee190c69caa%40googlegroups.com.

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

Re: Announcing the pandoc acronym filter

[Gwern Branwen]

On Mon, Feb 24, 2020 at 7:11 AM Mirko Boehm <mirko-RoXCvvDuEio@public.gmane.org> wrote:
> I am considering a mode of operation where acronyms don't need to be marked. It is difficult to be consistent with that, though. For example, how exactly would you know what the expanded text is? Still thinking about it.

One possibility: use of span titles to provide
abbreviation/acronym/terminology definitions everywhere, potentially
automatically.

Right now, the plugin homepage description implies that you are doing
nothing with the later uses of the acronym, which is not helpful: what
if I forgot or missed the first defining instance, perhaps because I
was linked to a section? How do I know it was ever defined? Do I have
to C-f every confusing term I might be interested in to see if the
first use in the page has a definition? But the later uses could be
annotated to be more helpful.

You're familiar with the popup tooltip titles from when you mouse-over
links and images, but most/all web browsers will pop up tooltips for
arbitrary elements when wrapped in a `<span>` with a `title=`
attribute. This is handy for doing things like providing documentation
on text which doesn't have a relevant link (for example, on gwern.net,
I use it in the metadata block to explain dates and other metadata
items where there's no sensible place to link to). So you could do
something like define "'GAN': 'Generative Adversarial Networks are NN
architectures which train multiple NNs &etc'" in a YAML config
somewhere (like in the page header for page-specific definitions), and
then instances of "[!GAN]" would be compiled to

1. the first instance: `<span class="abbreviation" title="GAN:
Generative Adversarial Networks are NN architectures which train
multiple NNs &etc">GAN (generative adversarial network)</span>`
2. subsequent instances: `<span class="abbreviation" title="GAN:
Generative Adversarial Networks are NN architectures which train
multiple NNs &etc">GAN</span>`

If the author wishes to typeset or highlight all abbreviations which
have definitions in some way, they can define CSS to do something with
the abbreviation class.
I don't know if you want to support PDF output; some googling suggests
that PDF can be made to support tooltip popups, but you'd have to take
a look to see whether that can be integrated sensibly.

This approach might make acronyms way easier to use as well.
Tooltips are, by default, extremely unobtrusive (the text looks
identical until moused over), so instead of the author being forced to
manually annotate every single instance of an acronym* & being nagged
by the tool if they forget... the plugin could offer a setting to
automatically annotate *every* match in a document without worrying
about spraying visual clutter everywhere & having false positives: if
a particular instance of 'XYZ' is not in fact the same as the 'XYZ'
acronym you defined, then any reader reading it will not be confused
and will never bother to mouse-over it. (You could implement it
similar to my auto-smallcaps filter, which searches through the text
for 3+ capitalized letters inside `Str` elements, and recursively
splits them apart to create new `Span` elements:
https://groups.google.com/forum/#!msg/pandoc-discuss/BDNfhctWJpg/bGk0wEtfBgAJ
) Should there be bad replacements, the auto-annotate mode could be
disabled, or the author can override specific instances in a variety
of ways, like making it not match ('G<!-- -->AN' or '\G\A\N' might
work) or providing additional syntax to force a literal without any
span annotation (perhaps something like '[!!GAN]'?).

* this is why I haven't tried to use the package: far too much work
for such a minor enhancement! I'd rather just write things out the
first time in the course of normal writing, instead of annotate a
gazillion instances of acronyms like "GAN" in my pages. Now, if I
could just have a centralized 'abbreviation.yaml' somewhere and write
down 'GAN: Generative Adversarial Networks are NN architectures which
train multiple NNs &etc', plug in a simple `Pandoc -> Pandoc` function
into my `hakyll.hs`, and  immediately get all uses side-wide annotated
with tooltips, that would be low enough effort that I would consider
it more seriously.

-- 
gwern
https://www.gwern.net

Re: Announcing the pandoc acronym filter

[Gwern Branwen]

It's worth noting there is a HTML5 semantic element intended for
precisely this already, <defn> and <abbrev>:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr
https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Advanced_text_formatting#Abbreviations

It functions much the same as a span with a title; the difference is
that it's explicit and semantic, so you can probably rely on browsers
to always display a tooltip and it'll be a little easier to manipulate
with CSS/JS, and it is somewhat more compact than <span>s with
classes/titles. The main difference, it seems, is what one might
regard as either a feature or a bug - because it's a semantic element,
web browsers may (inconsistently) style it for you:

> - Some browsers, like Internet Explorer, do not style it differently than a <span> element.
> - Opera, Firefox, and some others add a dotted underline to the content of the element.
>  - A few browsers not only add a dotted underline, but also put it in small caps; to avoid this styling, adding something like font-variant: none in the CSS takes care of this case.

So authors would have to opt-out of these possible stylings. Which
raises the question of whether opt-in or opt-out styling should be
preferred, in either the current manual mode or my suggested automatic
mode. In manual mode, probably opt-out is better: if you've gone to
the trouble of hand-writing some acronym annotations, you probably
want the reader to know they're there. But in an automatic mode, not
so clear: if you use a *lot* of particular acronyms, everything being
dotted and/or small-caps is probably visual clutter, requiring
additional CSS just to override it and you'd've preferred <span> and
opt-in styling; on the other hand, perhaps it is more common for
authors to use relatively few acronyms and so it's fine to default to
styling them and make acronym-heavy authors opt-out (theoretically it
should be only 1-2 lines of CSS to remove the underlining & smallcaps,
which is not *that* much of a burden)?

--
gwern

Re: Announcing the pandoc acronym filter

[Christophe Demko]

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

This is a useful filter.
But you could use the pandoc metadata to define your acronyms instead of an 
external file:


---

pandoc-acronyms:  aba:    shortform: ABA

    longform": a better acronym

  bba:

    shortform: BBA

    longform: beer brewing attitude

...


See https://pandoc.org/MANUAL.html#extension-yaml_metadata_block

Le jeudi 6 février 2020 12:47:22 UTC+1, Mirko Boehm a écrit :
>
> Hello there,
>
> for a recent article I needed a way to automatically expand acronyms on 
> the first use. Since there was not a good solution for it, I implemented a 
> pandoc filter that does the trick. You can find it here: 
> https://gitlab.com/mirkoboehm/pandoc-acronyms It is distributed via pip: 
> https://pypi.org/project/pandoc-acronyms/ Once installed, it runs as a 
> stand-alone program in the usual pandoc filter way.
>
> Can I ask for some feedback? There are a couple of things to discuss:
>
>    - The syntax: Acronyms are marked like this: [!bba]. Does that clash 
>    with other naming schemes? It it sound?
>    - I would like to add a feature to generate an acronym index at a 
>    marked location in the document. What would be the best way to do that?
>
>
> To suggest improvements, feel free to add them as issues to the Gitlab 
> project so that they don’t get lost in the discussion thread.
>
> Best,
>
> Mirko.
> -- 
> Mirko Boehm | mi...-RoXCvvDuEio@public.gmane.org <javascript:> | KDE e.V.
> Qt Certified Specialist and Trainer
> Request a meeting: https://doodle.com/mirkoboehm
>
>

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/e29c102d-3612-4e6c-8fbc-687bd07ee864%40googlegroups.com.

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

Re: Announcing the pandoc acronym filter

[Mirko Boehm]

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

Hello Christophe,

> On 1. Apr 2020, at 10:24, Christophe Demko <chdemko-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 
> This is a useful filter.
> But you could use the pandoc metadata to define your acronyms instead of an external file:

Thanks, this is a useful idea. I was thinking about it, too. Does anybody know where I can find information how the panic metadata is made available to the filters? I am also looking for information on how to inject elements so that I can create an index of  acronyms at a marked spot in the document.

All the best,

Mirko.

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/8A6899E5-8D6C-4C13-BE3B-E0DF09876F50%40kde.org.

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

Re: Announcing the pandoc acronym filter

[John MacFarlane]

See the docs for this example
https://pandoc.org/lua-filters.html#replacing-placeholders-with-their-metadata-value

Mirko Boehm <mirko-RoXCvvDuEio@public.gmane.org> writes:

> Hello Christophe,
>
>> On 1. Apr 2020, at 10:24, Christophe Demko <chdemko-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> 
>> This is a useful filter.
>> But you could use the pandoc metadata to define your acronyms instead of an external file:
>
> Thanks, this is a useful idea. I was thinking about it, too. Does anybody know where I can find information how the panic metadata is made available to the filters? I am also looking for information on how to inject elements so that I can create an index of  acronyms at a marked spot in the document.
>
> All the best,
>
> Mirko.
>
> -- 
> 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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/8A6899E5-8D6C-4C13-BE3B-E0DF09876F50%40kde.org.

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/m2imihwzxh.fsf%40johnmacfarlane.net.

Re: Announcing the pandoc acronym filter

[Christophe Demko]

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

in python (panflute) doc.get_metadata() returns the metadata of the document

Le jeudi 6 février 2020 12:47:22 UTC+1, Mirko Boehm a écrit :
>
> Hello there,
>
> for a recent article I needed a way to automatically expand acronyms on 
> the first use. Since there was not a good solution for it, I implemented a 
> pandoc filter that does the trick. You can find it here: 
> https://gitlab.com/mirkoboehm/pandoc-acronyms 
> <https://www.google.com/url?q=https%3A%2F%2Fgitlab.com%2Fmirkoboehm%2Fpandoc-acronyms&sa=D&sntz=1&usg=AFQjCNGF9fQMLvKr3H46gmo2X66Ornb3rA> It 
> is distributed via pip: https://pypi.org/project/pandoc-acronyms/ 
> <https://www.google.com/url?q=https%3A%2F%2Fpypi.org%2Fproject%2Fpandoc-acronyms%2F&sa=D&sntz=1&usg=AFQjCNEfikUTDaghqLuNrfvBL0g82rOaCQ> Once 
> installed, it runs as a stand-alone program in the usual pandoc filter way.
>
> Can I ask for some feedback? There are a couple of things to discuss:
>
>    - The syntax: Acronyms are marked like this: [!bba]. Does that clash 
>    with other naming schemes? It it sound?
>    - I would like to add a feature to generate an acronym index at a 
>    marked location in the document. What would be the best way to do that?
>
>
> To suggest improvements, feel free to add them as issues to the Gitlab 
> project so that they don’t get lost in the discussion thread.
>
> Best,
>
> Mirko.
> -- 
> Mirko Boehm | mi...-RoXCvvDuEio@public.gmane.org <javascript:> | KDE e.V.
> Qt Certified Specialist and Trainer
> Request a meeting: https://doodle.com/mirkoboehm
>
>

-- 
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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/c014bcce-419f-446c-bb67-512304e4dfc1%40googlegroups.com.

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