Write TUGboat 44:1 article about attributes and attribute contexts

[Witiko]

In Markdown 2.22.0, we will support attribute context renderers for headings, bracketed spans and fenced divs, and links, images, code spans, and fenced code. We should write a TUGboat article that introduces the concept of attributes and attribute contexts and show how coders can style attributes with the Markdown package.

[Witiko]

Putative outline

1. Introduction
2. Attribute contexts
3. Examples
4. Conclusion

[Witiko]

Here is the current copy of the article: https://www.overleaf.com/read/dshtsnnmtshs

[krono]

Looks good!

[Witiko]

I will be sending the article to Karl Berry on Sunday evening. Reviews are welcome. 😉

[Witiko]

@writersglen: This article addresses your requests for giving more control over formatting to the hands of authors. I will appreciate your review.

[Witiko]

Dear Karl, attached, you will find my submission for TUGboat 44:1: Attributes in Markdown Best, Vít

[writersglen]

Hi Vit,I can’t give your article a fair review since it’s far too technical for the self-publishers I know and work with and not at all clear to me how to apply your new features.Best wishes,LloydSent from my iPadOn Mar 24, 2023, at 9:41 AM, Vít Novotný ***@***.***> wrote: @writersglen: This article addresses your requests for giving more control over formatting to the hands of authors. I will appreciate your review. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[Witiko]

@writersglen Thank you, that is useful feedback. I was trying to concentrate on the non-technical stuff (what are attributes and how to type them) in Section 1 (Writer's workshop) and leave the technical stuff (how to format the output) for sections 2 and 3. Perhaps the introduction is too technical for the self-publishers?

[writersglen]

Yes. You need simple how-tos with real-world examples.L.Sent from my iPadOn Mar 28, 2023, at 1:19 AM, Vít Novotný ***@***.***> wrote: @writersglen Thank you, that is useful feedback. I was trying to concentrate on the non-technical stuff (what are attributes and how to type them) in Section 1 (Writer's workshop) and leave the technical stuff (how to format the output) for sections 2 and 3. Perhaps the introduction is too technical for the self-publishers? —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[Witiko]

@writersglen I am sorry to hear that. I hear good reviews from both LaTeX programmers and technical writers, so I suppose I am mostly failing at communicating with authors of fiction and non-technical prose who are not familiar or comfortable with LaTeX or programming in general. I will be happy to hear any constructive feedback that you can offer, i.e. what about applying the new features is unclear from my explanation, since this can make the article easier to digest for readers.

[writersglen]

Consider that the average self-publisher is quite comfortable typesetting their books with MS Word, e.g. they publish books that fall short of trade quality. So that cuts severely into marketing potential. Well more than one million books are self-published each year in the U.S. alone, but most sell fewer than 100 copies. Most do, however, have little problem publishing eBooks and many do quite well.We’re asking self-publishes to take a giant, scary, step from Word to LaTeX, from LaTeX to markdown. Unless we can make a compelling case, most would rather not bother. It’s challenge enough to write a book in the first place.You can argue that you’d rather not address the needs of this very large potential user base. But that’s a rather elitist, maybe even defeatist position, isn’t it?The issue comes down to time. It takes many precious hours to write a book. And more to bring it to print, and many more to market it. Your package is only useful if it saves time.So, any book typesetting edge case that requires dropping out of markdown and into LaTeX or TeX or Lua is a show-stopper.The two edge cases, aside from your disinterest in addressing the needs of self-publishers, that compelled me to defer publication of Publish Beautiful, are these:1. Lack of control over vertical spacing. If you scan the PB ms, you’ll see inconsistent (too tight or too loose) vertical spacing at various points in the ms.2. Inability to scale and appropriately position images.No doubt there are more such edge cases. But until I can publish a beautiful book with markdown with minimal technical effort, I’m not interested. Nor will most self-publishers I know.L.Sent from my iPadOn Mar 28, 2023, at 8:29 AM, Vít Novotný ***@***.***> wrote: @writersglen I am sorry to hear that. I hear good reviews from both LaTeX programmers and technical writers, so I suppose I am mostly failing at communicating with authors of fiction and non-technical prose who are not familiar or comfortable with LaTeX or programming in general. I will be happy to hear any constructive feedback that you can offer, i.e. what about applying the new features is unclear from my explanation, since this can make the article easier to digest for readers. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[Witiko]

Consider that the average self-publisher is quite comfortable typesetting their books with MS Word [...] We’re asking self-publishes to take a giant, scary, step from Word to LaTeX, from LaTeX to markdown. Unless we can make a compelling case, most would rather not bother.

I am asking self-publishers to accept the division of labor between authors, designers, and programmers, where authors prepare the content, designers prepare a design spec, and programmers prepare a template based on the design spec and take care of the LaTeX side of things. Until version 2.15.0 of the Markdown package, I was also asking self-publishers to type their documents in Markdown rather than MS Word. Since version 2.15.0, there is no additional ask and self-publishers can just type their manuscript in MS Word, see Section 2.3 of our article for more details.

I acknowledge that programmers and designers cost money, so any piece of software that allows self-publishers to cut the middle-man is welcome. The Markdown Package for TeX is not such a piece of software. Arguably, recent advances in AI will likely make it possible to replace the programmer and the designer by an AI model who will write the necessary code for the self-publisher.

The two edge cases [...] that compelled me to defer publication of Publish Beautiful, are these:

1. Lack of control over vertical spacing. If you scan the PB ms, you’ll see inconsistent (too tight or too loose) vertical spacing at various points in the ms.

Under the design philosophy of Markdown, vertical spacing is a presentation aspect of a document that should not be controlled by the self-publisher but by the template prepared by the programmer.

2. Inability to scale and appropriately position images.

I show how self-publishers can scale images in Markdown using attributes in the last example of Section 1 in the article that I asked you to review. In the last example of Section 2, I show how a programmer would implement such scaling, although that's rather technical and likely not as interesting to you.

Similarly, attributes can be used to influence the positioning of images. The self-publishers could type ![image](image.png){position=top} and then instruct the programmer to make sure that position=top means that the image should appear on top of a page.

Under the design philosophy of Markdown, both scale and position are presentation aspects, so it is better to leave them to the template that you are using, or have a number of coarse-grained classes of images such as {.small}, {.large}, and {.x-large} with their own rules for scaling and positioning. This allows the self-publisher to focus on the content instead of micromanaging the presentation aspects of their work.

[Witiko]

Dear Karl, thank you for your review. As you noticed, there is a systematic error in examples from Section 1 in the placement of \begin{markdown} and the omission of \begin{document}. Thanks for noticing it, it has evaded both me and two early readers somehow. I am in favor of adding example output to the first example in Section 1, since it's the only remaining example that has an obvious rendering that we can show. For completeness, I can also show a possible output for the last example in the Introduction just to drive home the idea that attributes can be styled in various ways. I will make sure not to exceed the current page count. Just a thought: are you happy with the red text in Section 2? I assume it will be printed in gray in TUGboat. I can certainly add a note explaining that colors have been grayscaled throughout in the printed article as we did in [an earlier article][1], or better yet: I can update the example to use e.g. underline instead of color. Please, let me know what you think and when you'd like to have the updated article ready. [1]: https://www.tug.org/TUGboat/tb41-3/tb129novotny-frozen.pdf#page=2 Best, Vit