feature: more class tags for epub template

brainchild0 commented 5 years ago

The default template for EPUB output creates a title page with the following XHTML body.

<body epub:type="frontmatter">
<section epub:type="titlepage">
  <h1 class="title">Oliver Twist</h1>
  <p class="author">Charles Dickens</p>
</section>
</body>

The title and author elements are the familiar HTML tags, also used in the book chapters, given appropriate class names.

Suppose someone wants to format the title page following a classic style. The title and author are spaced close together relative to the height of the page, then they are, together as a block, vertically positioned such that the center of the block is just above the center of the page. To achieve this effect with CSS, a style needs to select the block containing the title and author. But this <section> element has no class designation, which would make selecting it easy, and can only be distinguished from other <section> elements by the value of its epub:type attribute. The CSS3 profile specified by EPUB has a feature called attribute selectors, which includes XML-namespace support (though these selectors are new to version 3), but this feature is inconsistently supported by readers. Meanwhile, if the <section> element is assigned a titlepage class name, or anything else unique, then it would be trivial to select it. Such a class attribute is not redundant with the EPUB attributes, as the former facilitates the internal relation between document and stylesheeet, and the latter is understood by the reader.

Suggestion: Insert additional class tags into the EPUB template to facilitate selection of specific blocks that otherwise have no distinctive selection criteria.

brainchild0 commented 5 years ago

Thanks. The title page block is just an example. Other locations, such as chapters, contain epub:type attributes as well, but no class tags, and additional class tags need not be limited to such places where epub:type tags already appear. More class selectors in more places, do little harm, and afford more options to stylesheet authors to create styles that behave reliably and consistently across display environments.

jgm commented 5 years ago

I'm happy to put in specific classes to address particular needs that people have, but I'm a little reluctant to scatter them willy-nilly through the template, since it clutters the namespace of available classes. (People might be adding their own class names, after all.)

brainchild0 commented 5 years ago

I respect the sensibility of avoiding namespace clutter, but please reflect on whether the present discussion may entail a richer set of considerations than the one you have used to reach your conclusion.

A few observations:

Parts of a book or formatted section have well-defined names following widely-agreed precepts. Unlike in a file system or software project, it is unlikely that two individuals accidentally choose the same name for different referents.
Risk of namespace collisions can be mitigated with prefixes for names, though this approach has many deficits.
Support for a rich set of class names that can be switched by a parameter is better than no support.
Support for a user-defined mapping of class names is possible, though difficult to use, as well as having other weaknesses.
Identifying a dozen important style elements will not initiate a course toward unreasonable rates of collisions in the namespace.
At a minimum, assigning a matching class name for each possible value of epub:type seems fitting.

Ultimately, though, a thoughtful review of the design considerations underlying style sheets may quell your fears about pitfallls to adding an abundance of class names. Stylesheets in the simplest case simply separate content and style provided by the same author, but largely their function is to make possible the construction of a document with content authors and style designers working separately without the demand of having knowledge of the other's work. The shared understanding is reduced only to rich set of class and element names, Document writers are expected to refer to each class name wherever appropriate, such that style designers can reliably select elements, to be matched to styles, with granularity as fine as desired in any case. The style designer never needs to request new classes to be added to the document, because the class names are defined to eliminate this need.

The conservative approach you are proposing is to wait until a style designer requests a new class name, and only then add it limits the usefulness of the system compared to the optimal, intended scenario. You are also suggesting that the user to add class names, which of course is only necessary if no class names yet exists for the desired referent.

Suppose a designer wishes to create carefully designed style sheet for use in any book generated at any future time by Pandoc's EPUB engine. Or suppose a book author wants to send his book to a designer, hoping to receive back professional-looking styling not limited by Pandoc's currently restricted set of selection criteria. Why should any designer be limited by what has been requested earlier? Why not specify a set of classes large enough and detailed enough that whatever selections need occur in any case are almost certainly possible?

Not to be too cheeky, but it is a bit like selling a car that comes with three wheels and an unused set of wheel studs, for the eventuality that the owner may choose to augment the vehicle with a fourth wheel. If a car needs four wheels, why not sell a car with four wheels?

If all the types of text in the book are tagged with fitting class names, then neither the designer or the user ever needs to want for augmenting the number of classes.

jgm commented 5 years ago

I think I'd be okay with the general principle of having a class everywhere we currently have an epub:type attribute (except perhaps cases like the TOC where we have an id that can be matched on).

Does this cover it?

brainchild0 commented 5 years ago

My suggestion is to apply to the XHTML content a rich set of class tags that make it unlikely that anyone trying to stylize the document would ever say, "I would like to achieve a particular visual effect, but I am unable to do so, because there is no class identifier specific to the appropriate elements." In such a case, I find little drawback. It is unlikely that someone would ever say, "There are many class tags in the document, but none for the class need. I would like to add a class, but I am unable to do so because the namespace is too cluttered."

having a class everywhere we currently have an epub:type attribute (except perhaps cases like

I plainly think it a big improvement. I will not say that I agree that it is optimal, for the reasons I have presented. I will certainly take it over no change, and hope that the more complete augmentation can at least be left open for later consideration.

brainchild0 commented 5 years ago

This issue remains closed despite the appearance of agreement that at least some action is appropriate.

Can the issue be opened, to prompt future work?

jgm commented 5 years ago

I'll open it but I'm not sure there's agreement. If it's just a few people who need this, they can use custom templates easily enough. If it's a popular request, it might be worth doing.

brainchild0 commented 5 years ago

I thought perhaps it was agreed that some action is helpful, even if which action is still unresolved.

I understand the lack of desire to commit resources to issues that might not affect a large number of users.

In this case, I would ask to you consider that if the number of users currently affected by this issue is small, it is likely because of the small number of users who are currently using the tool to create good-looking EPUB documents. Such as small number is hardly surprising, considering that at the moment, you are offering two options for EPUB output, on opposite ends of a spectrum: 1) accept the default, spartan formatting, or 2) create an entire template, either from scratch or by forking a default. While both options are agreeable to certain use cases of Pandoc, it seems that overwhelmingly the preferred use of Pandoc is with included templates while adjusting appearance by additional options and data.

At the moment, the EPUB output mode appears not to offer much help using this intermediary option. As EPUB utilizes the XHTML/CSS paradigm of separating the logical layout and content from physical formatting considerations, there is little actual challenge in generating XHTML pages that can be modified flexibly by custom CSS templates.

If Pandoc would ever be widely used for creating EPUB documents, it is likely to occur only after such improvements are adequately considered.

jgm commented 5 years ago

Okay, I'll add it to the 2.8 milestone and try to decide what to do before long.

mb21 commented 5 years ago

This would only require template changes, right? So if someone has class clashes, they can simply use the old template as a custom template...

jgm commented 5 years ago

Reviewing this, I believe this is no longer a template issue. We already added a class in the one place requested above in the template. The request now concerns places where the HTML writer inserts epub:type attributes but no class. Looking at the reader, I'm seeing

a epub:type="noteref"
li epub:type="footnote"
section epub:type="footnotes"

I'd have no objection to adding a class to these places if it's important. I don't see any other places (besides the body tag) where epub:type is added by the writer. Of course, users may add epub:type manually in header attributes, but if they're doing that they can also add a style.

mb21 commented 5 years ago

Sorry if I'm missing something, but you can target those with CSS as well, right?

li[epub:type="footnote"] {
  /* my CSS */
}

see https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors

jgm commented 5 years ago

See the original post:

The CSS3 profile specified by EPUB has a feature called attribute selectors, which includes XML-namespace support (though these selectors are new to version 3), but this feature is inconsistently supported by readers.

brainchild0 commented 5 years ago

Yes, as I originally observed, NS-aware attribute selectors are undependable, because a substantial fraction of readers lack support, lack a commitment to maintaining support, or lack any clear plans to add support.

However, the deeper issue is getting lost, I am afraid, in this discussion. Understand please that the objective is not to make elements selectable as long as they already have EPUB types, but to make all elements selectable that might be of interest to anyone creating styles. As no one has yet given any cause to conclude that the former is a superset of the latter, I find no reason to limit elements given class identifiers to those already having EPUB types. Which elemets have EPUB types is ultimately a red herring that will not aid in the decision of which elements ought to have class identifiers.

I think it is important to choose an option for this feature that actually will solve the problem originally described.

Considering that class identifiers are specifically intended to allow style sheets to select elements indented to have like stylization, and that no feature of XHTML is more suited for reliably facilitating selection of elements as such, I find no compelling reason to be stingy in assigning class identifiers to elements.

What are your main concerns about more liberal use of class identifiers? You are principally worried, as you explained earlier, about namespace collisions?

jgm commented 5 years ago

Why don't you tell us where you think classes are needed? In most cases that I can think of, either the element names themselves should suffice for styling, or there are already classes. Maybe there are exceptions? Let us know what they are.

brainchild0 commented 5 years ago

Do you want me to create an exhaustive list? My concern would be that, even if an exhaustive list of my creation were adopted immediately, ultimately the maintainer of the template must adhere to the principle being described, if the benefit is to be preserved across successive updates.

Just looking briefly at a sample output document, neither the chapter name nor the chapter paragraph text have class identifiers. These are examples, not an exhaustive list.

alerque commented 5 years ago

The original issue post stated:

Insert additional class tags into the EPUB template to facilitate selection of specific blocks that otherwise have no distinctive selection criteria.

In theory this makes sense to me. If there is not a way to target styles to specific kinds of blocks there needs to be. But that doesn't seem to be where you are headed now:

Just looking briefly at a sample output document, neither the chapter name nor the chapter paragraph text have class identifiers.

As far as I can tell chapter names and body paragraphs are already immanently targetable based on their tags. What elements types coming out of Pandoc's AST end up without a way to uniquely target them my type in a CSS rule?

Note that there are usually ways to do this with selectors other than classes, classes would only need to be added to disambiguate content which comes from different element types in Pandoc but due to restrictions in the output format get rendered with ambiguous tagging.

brainchild0 commented 5 years ago

As far as I can tell chapter names and body paragraphs are already immanently targetable based on their tags. What elements types coming out of Pandoc's AST end up without a way to uniquely target them my type in a CSS rule?

Note that there are usually ways to do this with selectors other than classes, classes would only need to be added to disambiguate content which comes from different element types in Pandoc but due to restrictions in the output format get rendered with ambiguous tagging.

This conversation can go in a multitude of directions, but I prefer that it be targeted to specifically what you have in mind. For clarity, would you please give your best suggestion for how the chapter names and chapter text ought to be selected? Note that such a suggestion is useful only if it selects the stated target, and no other.

Authors should be able to design style sheets that are simple to write, clear to read, and robust across modifications over successive template versions. Although I agree that it is possible to do as you say generally, I offer my friendly challenge above because I doubt any solution exists that satisfies these important constraints.

alerque commented 5 years ago

For clarity, would you please give your best suggestion for how the chapter names and chapter text ought to be selected?

Yes, my suggestion would be:

/* Selector for chapter titles */
h1 { }

/* Selector for normal chapter body text */
p { }

In what way do these selectors not meet your criteria?

brainchild0 commented 5 years ago

In what way do these selectors not meet your criteria?

They are not robust, and not unique to the desired targets.

Currently, the h1 selector applies both to book title and chapter titles. The p selector applies to all body text as well as to certain non-title elements on the title page, such as author. A designer attempting to select only for chapter names, or only for body text of the top level (i.e. chapters but not sections or subsections), cannot successfully utilize either suggested solution.

Furthermore, the current choice for which specific XHTML element tags correspond to which logical document parts is one that ought to be able to change in the template without breaking previously existing style sheets.

Essentially, you are positing a robust, one-to-one mapping of XHTML elements to logical document parts, when in fact the mapping is not robust, and is one-to-many (or perhaps, in general, many-to-many).

alerque commented 5 years ago

Yes? That's how CSS works. CSS stands for Cascading Style Sheets, and it works quite well for this purpose. When I'm styling a book I generally want my rules to cascade through the whole DOM. I start with the general things (rules that should apply to all paragraphs whether root level or inside blockquotes) then work my way down to more specific tweaks for each.

/* Set everything that applies to all headers */
h1 { }

/* Set rules that only apply to the title page */
.titlepage h1 { } 

/* Set rules that apply only to chapter titles */
.level1 > h1 { }

(Note the > selector may or may not be what you want here depending on whether you want H1 tags nested inside other sections levels to be selected or not.)

Another thing to note is that I really wouldn't like to see EPUB's coming out of Pandoc be different from generic ones found elsewhere. I would like to be able to use CSS themes from other places and apply them to Pandoc generated books and vise-versa. In other words I don't want Pandoc to try to "fix" the EPUB format and make it into something that isn't readily cross compatable with other EPUB tooling.

Please give a specicfic example of an element that is uniquely identifiable in the Pandoc AST and not targetable with CSS selectors and existing markup.

brainchild0 commented 5 years ago

Yes? That's how CSS works. CSS stands for Cascading Style Sheets, and it works quite well for this purpose. When I'm styling a book I generally want my rules to cascade through the whole DOM. I start with the general things (rules that should apply to all paragraphs whether root level or inside blockquotes) then work my way down to more specific tweaks for each.

Cascading is relevant if an element matches multiple selectors. This consideration is unrelated to the current discussion. Previously, you gave a single selector that applies to multiple elements, some of which are not desired for selection.

Also, you may be confusing specificity with inheritance, the latter being distinct from cascading and related to styles propagating down the DOM tree. It is equally unrelated to the current discussion.

Your more recent example requires a more specific rule in order to avoid the less specific one from being applied where not desired. This example does invoke cascading, and also presents an unnecessary burden to the designer of a style sheet merely for the simplest objective. Everywhere a rule is created that correctly applies to an element in one place, at least one other rule must be given to suppress the same rule from applying to an element in another place. We are given a choice, using this scheme, between many rules for a small effect, or few rules for a large effect. This choice is unpleasant, whatever the intent.

(Note the > selector may or may not be what you want here depending on whether you want H1 tags nested inside other sections levels to be selected or not.)

Yes, in some cases child selectors will solve some of the problems previously mentioned. However, far from solving, they exacerbate, the robustness problem. And they prevent the style sheets from being simple to write and clear to read. I asked whether you could offer a single solution that satisfies all constraints, not a separate solution for each constraint. It seems that you may be searching for a convoluted solution in order to prove that a simple one is unnecessary. My interest is precisely the reverse.

Another thing to note is that I really wouldn't like to see EPUB's coming out of Pandoc be different from generic ones found elsewhere. I would like to be able to use CSS themes from other places and apply them to Pandoc generated books and vise-versa. In other words I don't want Pandoc to try to "fix" the EPUB format and make it into something that isn't readily cross compatable with other EPUB tooling.

What is a generic EPUB? If a convention is in use describing preferred XHTML elements and attributes for each logical document element, please provide a reference. I have never seen such a convention.

Please give a specicfic example of an element that is uniquely identifiable in the Pandoc AST and not targetable with CSS selectors and existing markup.

No. I already conceded at several points that for any particular version of the EPUB template, the selectors exist in principle that apply to the appropriate targets. The relevant issue is whether elements can be selected using style sheets that are clear and simple, consistently functional in most existing readers, and unlikely to break with design changes to the template. If your object is to extol the full semantic breadth of CSS3, then I would ask you to find a more appropriate venue.

My suggestion is to avoid creating documents that are impoverished of useful class identifiers, rather than depending on the most advanced (and unreliably implemented) features of CSS to compensate for such a poverty.

alerque commented 5 years ago

The selector .titlepage h1 {} is hardly an advanced CSS3 selector with an unreliable implementation. I still don't see an example from you of something that cannot currently be easily targeted using widely supported selectors.

brainchild0 commented 5 years ago

The selector .titlepage h1 {} is hardly an advanced CSS3 selector with an unreliable implementation. I still don't see an example from you of something that cannot currently be easily targeted using widely supported selectors.

Child selectors are advanced. Attribute selectors are unreliable, as discussed, and incidentally, also advanced.

The selector above is neither, and I never said that it was either. But the other features were mentioned, so I must characterize them appropriately.

Suppose you want to change the styles only such that all chapter titles are now to be underlined. Such should be possible with a single rule, which works in all readers, with all future template versions, and makes no reference to any XHTML element name.

It is frivolous to suggest all kinds of other solutions when only the one above is needed, and thankfully, also extremely feasible.

alerque commented 5 years ago

I haven't suggested using attribute selectors. I realize the state of many ebook readers' support for CSS is piss-poor and often years behind browsers. That being said child selectors (or as some specs refer to the syntax, the 'child combinators') (>) were introduced over a decade ago in CSS2 and as far as I know are universally supported at this point.

Note also that even the child combinator is not required, descendant selectors (CSS1 here folks) is enough to get the job done, albeit with a little more care to reset places where inheritance is not desired. The child combinator just makes it a little simpler.

In fact I would argue that if child selectors are considered to advanced, what you are actually trying to compensate for is not an impoverished document but ignorance of CSS.

makes no reference to any XHTML element name

EPUB is inherently a wrapper around HTML documents and CSS is used to style elements in those documents. If what you want to accomplish is removing all knowledge of element names from somebody writing CSS rules for an EPUB then I personally think Pandoc is not the place to fix this. Perhaps you can hook your designers up with a CSS preprocessor template with aliases for matching each element in a "flat" layout that requires no understanding of element, selectors, or inheritance.

brainchild0 commented 5 years ago

I haven't suggested using attribute selectors.

No one said you did, but you several times offered a challenge that, as previously discussed, can currently be solved in no other way.

In fact I would argue that if child selectors are considered to advanced, what you are actually trying to compensate for is not an impoverished document but ignorance of CSS.

Child selectors are too advanced with respect to this issue, not because of ignorance of CSS, but because they are completely unneeded.

EPUB is inherently a wrapper around HTML documents and CSS is used to style elements in those documents. If what you want to accomplish is removing all knowledge of element names from somebody writing CSS

I do not want to remove all knowledge of anything, but it is best to eliminate user dependency on implementation details.

@alerque, I have tried to be patient, but I am growing frustrated. I want to make it as simple as is feasible for users to contribute their own style sheets that control style as fully as desired, and I believe users will want the same. I have no interest in what you think is not advanced or who you think is ignorant.

If your approach is to make the solution complicated just because CSS makes it possible, or your object is to explain all the features of CSS to a curious audience, please find the appropriate places for such discussions.

I am sorry to be dismissive but I am frustrated with how quickly we are travelling to nowhere.

jgm commented 5 years ago

@brainchild0, you are right that we should provide ways to style things that don't rely on unreliably supported attribute selectors. That motivates adding classes in these cases:

a epub:type="noteref"
li epub:type="footnote"
section epub:type="footnotes"

and I'm happy to do that. But I agree with @alerque that we shouldn't add classes when they're not necessary for styling. So I'm not inclined to complicate all the HTML writer code so that, in epub, it emits things like <h1 class="chapter">.

I can see you disagree, but since this thread has been pretty exhaustive, I don't think we should spend more time on this issue.

However, if there are more cases (besides those above) where classes would be needed because it is currently impossible to style things without them using well-supported CSS methods, please feel free to suggest them. Otherwise I'll add classes in the above cases and we'll call it done.

brainchild0 commented 5 years ago

I am sorry that the only outcome of this issue would be to make stylizing document elements possible. I am hopeful that EPUB output can evolve into something much more usable.

A tool is very hard to use if adding the simplest style changes requires a style sheet that 1) employs the knowledge that chapter titles are currently represented by h1 elements that are children of elements with level1 class identifiers, 2) requires representation of this entire structure in a rule selector, and 3) breaks completely and totally the very moment the template designer chooses to change any single part of this structure.

I have invested a considerable amount of time explaining the sense in helping users avoid needing to write style sheets that are verbose, obtuse, and unstable, and I understand I have failed. I have equally invested time trying to understand any practical concerns related to adding a rich set of class identifiers, and I have equally failed.

I am sorry if it might appear that I take a sour tone. Yet in truth, as I have lost belief that this discussion is helping to make Pandoc better either for me or anyone, I have also lost both the motivation to continue it and any sense of how I might do so without being in discord with its other participants.

I will continue to use Pandoc for output documents of types other than EPUB, I will also continue to open issues if I think that doing so will prompt discussions about making the application more stable and usable, as I have done several times before with good effect.

jgm commented 5 years ago

Yes, if we were to change the way the writer represented chapters (moving from h1 to h2 for example), then existing stylesheets would break. But using classes would leave us in a similar situation. It would still be the case that if we changed the classes we used (moving from chapter to pandoc-chapter for example), existing stylesheets would break.

Moreover, you seem to be under a misapprehension. Changes to the template could not break the

.level1 > h1

selector. The structure it refers to is generated by the EPUB writer and has nothing to do with the template. The writer ensures that each chapter is enclosed in a section element with class level1. In many ways this gives you more flexibility than attaching a class to the h1 element, since you can use this to style all of the subordinate content in a chapter (including subheads, borders, etc.), and you still have the ability to style just the chapter heading if you like.

Anyway, I'm glad to have your feedback and I'll keep thinking about it. feel free to bring this up on pandoc-discuss, if you like. If enough other people who use pandoc to produce epubs feel the way you do, it might sway me.

jgm commented 5 years ago

I think adding a chapter-title class to chapter headings would be fine, if it makes things more convenient.

jgm commented 5 years ago

I've added a chapter-title class. That was easy to do with just a change in the EPUB writer (it didn't require changes in the HTML writer).

I know this probably won't satisfy you, @brainchild0, but if there are specific other requests it's probably better to make them in separate issues, so this doesn't expand without limit. I'm not interested in emiting things like <p class="paragraph">, though, and I think asking users to put a rule on h2 or .level2 > h2 if they want to style subsection headings is not unreasonable. True! We could change pandoc to use something other than h2 here. But we could also change a class.

brainchild0 commented 5 years ago

Yes, if we were to change the way the writer represented chapters (moving from h1 to h2 for example), then existing stylesheets would break. But using classes would leave us in a similar situation. It would still be the case that if we changed the classes we used (moving from chapter to pandoc-chapter for example), existing stylesheets would break.

Obviously, the statement you make about changing the name of the class is true on its face. However, the more general statement you make, which is the core of the issue, that "using classes would leave us in a similar situation", I believe is rather deeply flawed, I am sorry to say. I regret if such a misunderstanding follows from an inadequacy in my earlier explanations. I may have considered inaccurately that my own assumptions would be equally apparent to everyone.

Class names are labels. Their content, the sequence of characters that comprise them, have no intrinsic meaning to anyone but the document and style creators. The reader has no static table of class names and their attributes. Class names become useful when a reference matches a referent. Once we agree that chapter_heading (I am not actually suggesting we use this name) is the label we will use to represent the physical formatting elements (in the case of XHTML, the document nodes) that constitute the chapter heading, we are free to preserve this label, and ought to do so, if even for no other reason than to preserve our agreement, regardless of which particular physical formatting elements do in fact constitute the chapter heading now or in the future. Meanwhile there are innumerable reasons to change the elements, in your example h1 to h2, notably to change or to improve document appearance. These reasons derive from the element names being specially recognized by the reader as part of the XHTML specification. We have limited freedom of which XHTML elements to choose in any context, because which names we use affects what the reader does with the elements. We must accept the possibility that some time in the future, we would change the XHTML element, or the more generally, the structure of a subtee of the XHTML document, because doing so is the only way to achieve desired changes to the appearance of the output.

In the case of class names, there is no reason to make a change except to change the agreement that was previously made. As such, our desire not to break this agreements is enough to ensure that no change will be made to any class name.

Basically, XHTML element names are part of the contract between the XHTML document and the reader, and cannot be managed independent from how the reader understands them. Class names are part of the contract between document owner and style designer. They exist precisely because these two parties require a language between themselves that is completely theirs to determine.

As long as we decide that we will make an agreement to designate certain class names for certain purposes, and as long as we make no choice to violate that agreement, we are all able to take advantage of that agreement in ways that we cannot take advantage of current conditions that are outside of that agreement.

Think of shared libraries. Library maintainers frequently update function implementations, as well as add functions, but they remove existing functions that are exposed to applications, or change the names of such functions, only very conservatively, usually only for major releases, and usually concurrent or following announcements that backward compatibility will break.

Moreover, you seem to be under a misapprehension. Changes to the template could not break the
.level1 > h1
selector. The structure it refers to is generated by the EPUB writer and has nothing to do with the template. The writer ensures that each chapter is enclosed in a section element with class level1. In many ways this gives you more flexibility than attaching a class to the h1 element, since you can use this to style all of the subordinate content in a chapter (including subheads, borders, etc.), and you still have the ability to style just the chapter heading if you like.

Again, true on its face, but hardly the core issue, if you ask me. If you wish to correct what you perceive to be my representation of the internals of Pandoc, you may do so, and I am happy for the correction. But I am discussing the effect on the user when changes occur to Pandoc, whether in the software code that you call the writer or the auxiliary files you call the template. From my perspective, it is the same. When I obtain an updated version of Pandoc, the behavior may change in a way I find disruptive, or may not. It depends entirely on what the changes are in the version, and whether they are things I find disruptive. Obviously, part of properly managing a software project is realizing which changes a user it likely to find disruptive, and avoiding unnecessary frequency and severity of such changes, as well as managing the effect of such changes when they are yet made.

Both components contribute to what the user receives when invoking Pandoc to perform a particular conversion on a particular input. If you have a term that you prefer I use to refer to the combination of the writer and the template, then I am happy to use this term instead, to avoid further confusion.

Anyway, I'm glad to have your feedback and I'll keep thinking about it. feel free to bring this up on pandoc-discuss, if you like. If enough other people who use pandoc to produce epubs feel the way you do, it might sway me.

I think adding a chapter-title class to chapter headings would be fine, if it makes things more convenient.

We have started a 200 meter dash 7 months ago and haven't done any running. We have created a camp that moves 500 centimeters every few weeks. Why make only particular isolated changes when the goal is to make a larger set of related changes?

True! We could change pandoc to use something other than h2 here. But we could also change a class.

Not to beat a dead horse, but making this claim evidences a misunderstanding, which I must address, of practical issues, even while the claim itself is true. I hope I can clearly explain the issue, if I have not already succeeded, with another analogy. If you have a group of friends who all have different ages, then you might say that learning their names is useless because their ages are equally useful ways to identify them. If someone suggests that names are a more reliably identifier than age, noticing that age changes each year, you might then argue that names can also change. You might think you have discovered that name and age are equally problematic methods of identifying a particular individual from within your group of friends. Names can change. But we use names as identifiers specifically with the intention that the same person keeps the same name. We have no such freedom to act on a similar intention with age. Age is a fact determined externally, while a name is a label chosen for the purpose of identification. The changing of one's age is not only possible but inevitable. In contrast, the changing of one's name is possible, but rare, simply because it is never necessary, and because it is easy to notice that frequently changing it largely defeats the purpose of having it.

All I have really said in this entire discussion is that there are a group of objects that need to be referenced reliably, and in order to do so, they need to be given names.

Most of the responses I have received essentially take the form of telling me that other ways are in existence than assigning names to refer to these objects, while failing to offer any way nearly as useful as names. No one would ever raise any of the same objections to giving names to people. ("Two people might be given the same name." "People can be described by appearance instead of being identified by name." And on it goes.) It is really frustrating to hear these objections because this same problem has already been solved in innumerable other contexts, with great success and without anyone raising these objections, precisely in the way I am asking that we solve this problem.

jgm commented 5 years ago

I'm sorry, but I really don't understand what you're looking for. That's why I keep asking for specifics, and all I get in return are long sour-sounding polemics. (Meanwhile, I've implemented several of the specific things you've asked for.)

It sounds like maybe you do want <p class="paragraph">, <blockquote class="blockquote">, and so on. But I'm really not sure! That sounds like overkill to me. If you want to make some specific proposals, please do, in a new issue. (But pandoc-discuss would be a much better place to do it, so others who have a stake in this and use pandoc for epubs can chime in.) This issue is closed, so it's not a good place to comment further.

brainchild0 commented 5 years ago

I opened a new issue.

The reason for my not giving greater specific suggestions was that you had already asserted criteria that would exclude overwhelmingly the class tags that I would imagine suggesting. In fact, of the two I did suggest, you rejected both, before accepting, seemingly with reluctance, only one. As I had reached the view that your exclusion criteria followed from misguided concerns, or otherwise at least did not follow from well-founded concerns, I tried to address them in order to have hope that an actual comprehensive list had some chance of being seriously considered. Such is the reason for the series of contributions that you characterize, not completely unjustifiably, as "sour-sounding polemics".

Nevertheless, please remain open to contemplating the practical considerations that might lead to greater acceptance of these suggestions. I little doubt you will see the new issue that just opened.

jgm / pandoc

feature: more class tags for epub template #5269