Re: general attributes and yaml metadata block + the future of Pandoc

Re: general attributes and yaml metadata block + the future of Pandoc

[Lloyd R. Prentice]

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

This thread compels me to express several growing concerns that I have about the future of Pandoc.

To me, Pandoc stands side-by-side with my text editor and OS as my most essential digital tools. I think of Pandoc as an operating system for print and digital communication. John MacFarlane’s far-seeing creativity and hard work toward making Pandoc what it is deserves profound gratitude from the community.

The Pandoc ecosystem, by the nature of the problems it sets out to address, is complex and likely to become ever more so. The challenge is how to manage that complexity so Pandoc can continue to effectively address the many diverse cases and edge cases we are likely to throw at it. Pandoc documentation, excellent so far as it goes, reflects this complexity. Case in point,  I’ve spent hours scouring the web to find or understand how to develop a PDF book template that fits my need.

I do understand that that Pandoc has a modular architecture. Sadly, I don’t understand it well enough since I’m not an haskell nor lua programmer. But here are the few vague thoughts that I have been mulling over:

— As I see it, Pandoc is a pipeline of readers, interpreters, writers, and styling templates. Each stage in the pipeline is a set of distinct functional components. Each component delivers value to a segment, some small and some sizable, of the larger Pandoc community. As a Pandoc user there are many if not most of the components that I will never need to use nor care about. And I suspect this is true for every Pandoc user.

— Rather than thinking of Pandoc as a monolith, a Swiss Army Knife, it might serve us better to think of Pandoc as a tool supplier — the place we go to pick out precisely the set of tools that we need to plug into our communication pipeline. Each tool deserves it’s own description of purpose, descriptive use cases, and documentation. Ideally, documentation format would be standardized across components.

— This structure is similar to the complexity problem faced by the developers of UNIX. Their solution was to urge development of simple single-purpose tools with standardized IO so data can flow smoothly through the processing pipeline using the brilliant UNIX pipe operator. They then developed man pages to document these tools.

I’m guessing that John had something like this in mind when he thought through the Pandoc architecture. But somehow, to me at least, it doesn’t come across this way in the diverse Pandoc canon. This is particularly evident at the styling stage. 

— All this leads me to say that we can’t expect John MacFarlane to solve every problem and integrate every feature we might like to see. We need to step up as a community to help shoulder the challenging work of organizing, documenting, and developing a dynamic Pandoc ecosystem that meets our individual and collective needs. 

As a first step, perhaps, we can discuss and agree by consensus on a standard format for documentation and tutorials. 

As a second step we then need to take on the hard work of documenting each and every component in the system.

Apologies for the length of this post, but I hope it provides constructive food for thought.

Lloyd

Sent from my iPad

>> On Aug 22, 2020, at 4:34 AM, ch_...-S0/GAf8tV78@public.gmane.org <ch_819-S0/GAf8tV78@public.gmane.org> wrote:
> why aren't attributes supported in "normal" markdown?
> 
> John MacFarlane schrieb am Freitag, 21. August 2020 um 22:51:31 UTC+2:
>> 
>> You're doing it right -- but currently no format supports 
>> both yaml metadata and attributes. 
>> 
>> When we add suppport for yaml metadata blocks to commonmark, 
>> you'll be able to use that. 
>> 
>> Christian Müller <ch_...-S0/GAf8tV78@public.gmane.org> writes: 
>> 
>> > I would like to use attributes like the following 
>> > 
>> > *something*{.timing} 
>> > 
>> > which should render to 
>> > 
>> > <em class="timing">something</em> or alternatively <span 
>> > class="timing"><em>something</em></span> 
>> > 
>> > According to documentation I need the attributes extension. When I do --from=markdown+attributes 
>> > I get 
>> > 
>> > The extension attributes is not supported for markdown 
>> > 
>> > When I try commonmark --from=commonmark+attributes instead it does work. 
>> > However, I also need the Yaml meta data block. --from=commonmark+attributes+yaml_metadata_block 
>> > yields 
>> > 
>> > The extension yaml_metadata_block is not supported for commonmark 
>> > 
>> > Am I doing something wrong? I'd rather stay with markdown (it's an older 
>> > document) 
>> > 
>> > (using the official pandoc build for windows) 
>> > 
>> > pandoc.exe 2.10.1 
>> > Compiled with pandoc-types 1.21, texmath 0.12.0.2, skylighting 0.8.5 
>> > 
>> > -- 
>> > 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-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org 
>> > To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/a0460a16-04eb-4ff8-8159-4a22138967b7o%40googlegroups.com.
> 
> -- 
> 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/b88f4db2-e711-41b5-8223-87f90447753fn%40googlegroups.com.

-- 
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/956E6AE2-1BD4-4E4B-BE51-42DD7FE51F4C%40writersglen.com.

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