feature: more class tags for epub template #5269
Comments
|
Thanks. The title page block is just an example. Other locations, such as chapters, contain |
|
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.)
|
|
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:
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. |
|
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?
|
|
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."
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. |
|
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? |
|
I'll open it but I'm not sure there's agreement. |
|
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. |
|
Okay, I'll add it to the 2.8 milestone and try to decide what to do before long. |
|
This would only require template changes, right? So if someone has class clashes, they can simply use the old template as a custom template... |
|
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 I'd have no objection to adding a class to these places if it's important. |
|
Sorry if I'm missing something, but you can target those with CSS as well, right? see https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors |
|
See the original post:
|
|
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? |
|
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. |
|
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. |
|
The original issue post stated:
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:
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. |
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? |
They are not robust, and not unique to the desired targets. Currently, the 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). |
|
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 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. |
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.
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.
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.
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. |
|
The selector |
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. |
|
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') ( 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.
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. |
No one said you did, but you several times offered a challenge that, as previously discussed, can currently be solved in no other way.
Child selectors are too advanced with respect to this issue, not because of ignorance of CSS, but because they are completely unneeded.
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. |
|
@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: 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 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. |
|
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 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. |
|
Yes, if we were to change the way the writer represented chapters (moving from Moreover, you seem to be under a misapprehension. Changes to the template could not break the 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 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 |
|
I've added a 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 |
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 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.
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.
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?
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. |
|
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 |
|
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. |
The default template for EPUB output creates a title page with the following XHTML 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 itsepub:typeattribute. 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 atitlepageclass name, or anything else unique, then it would be trivial to select it. Such aclassattribute 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.
The text was updated successfully, but these errors were encountered: