Why does the default output of asciidoctor-pdf look so ugly?

Hello,

I had to write some documentation and did it with microsoft word. But I also wanted to try asciidoctor and I really like it.

But when I compare the word document and the output of asciidoctor-pdf, I must say, that the asciidoctor document looks worse. I was able to modify the look of the tables a little bit, though I have no CSS knowledge. Perhaps I could do more if I spend some time. BUT - why is the default-template.yml not adjustet more carefully? Does the develper expect everybody to work on the yaml file? And why? In my humble opinion the HTML output looks O.K., so why is the pdf so neglected?

Just my 2 cents
Ralf

--

Ralf Jahns wrote

But when I compare the word document and the output of asciidoctor-pdf, I must say, that the asciidoctor document looks worse.

This is kind of funny. What word document? I can make the one that would look worse whatever you can imagine of.

Default asciidoctor-pdf output is beautiful. Not perfect, but way way better than it was 1 year ago.

There are limitations on underlying pdf engine -- not everything "to make perfect typesetting" could be and is implemented -- this is the road we go together.

As for default template -- you don't have to change it in-place. You can and probably should create your own theme, extending default one, adding what you think make it not ugly. It is easy to do and very well documented.

If you want *default* theme to be adjusted -- create an issue in asciidoctor-pdf github, where it could be discussed/reviewed/accepted/rejected.

Sorry, I really didn't want to put down anyones work.

I, as a software developer, prefer to create documentation in the way asciidoctor works compared to writing a word document. When I was a student, I used LaTeX a lot and never had any complaints about its output.

Few weeks ago, I had a "SW architecture" training and asciidoc(tor) was recommended to us (as a sidenote, we didn't talk about that very long).  I was quite enthusiastic about it. My expectations were high. I also know NOTHING about the maturity of the asciidoctor project.

One more thing I really appreciate is the quick answer I got to my writings. In the forums of many big projects, you get no answer at all (at least from the maintainers).

The company I work for, provides me a word template for a software design description document. Nothing fancy! I really wanted to try asciidoctor and because I was able to spend the time at the moment, I did it. After "compiling" the adoc, I was a little (sorry) disappointed about the look. Of course, that is also a question of personal taste! And I only look at the PDF output, the HTML output is completely useless for me, but probably not for most of the other users!

But, after all, I still think that these things should be changed:

Headings should be closer to following text than to preceding text. That's the way it is in every book I could find.

Table lines should be black. Why would anyone make them grey??? Quickly checked 1.2 meters of sofware development books and additionally a few more other non fictional books. None with grey table lines! All tables have black lines. (Some have no vertical lines.) In my humble opinion, the heading line could get emphasized a little more (perhaps by a grey background).

More than one font should be used. Perhaps it could be done like in LaTeX, which uses two (different font for the headings).

Every user can do this by himself. But why? This is NO work compared to what is necessary to develop such a nice tool as asciidoctor. But it will give everyone a much nicer first impression about the output!

Best regards
Ralf Jahns

Ralf Jahns wrote

But, after all, I still think that these things should be changed:

Headings should be closer to following text than to preceding text. That's the way it is in every book I could find.

While I agree with this -- you have to understand that asciidoctor is not only about books. I do a lot of technical and business documentation (specifications) for example. And I had not a single issue with heading padding/margin.

Ralf Jahns wrote

Table lines should be black. Why would anyone make them grey??? Quickly checked 1.2 meters of sofware development books and additionally a few more other non fictional books. None with grey table lines! All tables have black lines. (Some have no vertical lines.) In my humble opinion, the heading line could get emphasized a little more (perhaps by a grey background).

Why do you think your preferences should be default?

Ralf Jahns wrote

More than one font should be used. Perhaps it could be done like in LaTeX, which uses two (different font for the headings).

Why 2 fonts? I don't think Serif body text and Sans-serif headings (or vise versa) is still relevant. And if it is what you think should be in your book/document it is really easy to do so.

I had it in my themes (serif headings, sans-serif body text) for  a long time.  You can have it too (good luck searching perfect font combination :) )

Ralf Jahns wrote

Every user can do this by himself. But why? This is NO work compared to what is necessary to develop such a nice tool as asciidoctor. But it will give everyone a much nicer first impression about the output!

Because people are different. They like different things. What you think is beautiful others might find not so appealing. That is why asciidoctor has theming system so everyone can tailor asciidoctor-pdf output for what they think is beautiful.

Again, if you still want to propose changes to default theme -- go for github issues. I don't think Dan would do anything out of forum discussions unless it is critical.

BTW, I guess you have created a theme and example document to demonstrate how it should look like?

Hello,

I expected answers like this. If everybody here but me thinks the output looks perfect, then fine. Keep it as it is. Probably I have an extraordinary taste (me and the publishers of numerous textbooks).

I think, it is bad advertisement for the project and will make people turn away.

I don't want to force changes (and of course can't do so), I only recommend to take care for this topic and tweak the default template a little bit.

Btw, I would recommend reading  "The Non-Designer's Design Book" by Robin Williams. It's my favourite.

Best regards
Ralf

Ralf Jahns wrote

Hello,

I expected answers like this. If everybody here but me thinks the output looks perfect, then fine. Keep it as it is. Probably I have an extraordinary taste (me and the publishers of numerous textbooks).

I think, it is bad advertisement for the project and will make people turn away.

You have options. Seems like you don't want to use any of them. If you have extraordinary taste (I got your sarcasm but still) you can express it in your theme. It is very, I repeat, very simple thing to do. You do it once and use it for all your docs.

Ralf Jahns wrote

I don't want to force changes (and of course can't do so), I only recommend to take care for this topic and tweak the default template a little bit.

Have a look into the github issues. There is a lot stuff going on there, major bug fixes, minor bug fixes, improvements and so on. Again, if you REALLY want your changes, you, at the very least, should create issue(s) there.

Just to clarify -- I am not an asciidoctor developer -- I am a user of it -- I
don't speak on behalf of asciidoctor community.

Asciidoctor(pdf) is an essential part of my daily routines so I try to
contribute to it as much as I can.

If I want something to be changed I do create issues in github -- this is
minimum of what I can do. There it might be classified, queued etc.

Having said that, your recommendations here, while valid, are just... words.

Hello,

you got my intention completely wrong. I don't want specific changes to be adjusted especially for me. I can do that by myself, as you suggest intensely.

What I want, is to highlight, that the output of the default theme, which is the thing every potential user like me sees first, doesn't look nice to me. I just want to suggest to take the design and typography aspect serious. If it is not, we can all use plain ASCII - no need to have asciidoctor.

I will not open an issue on github. The admin Dan Allen answered me, he is aware of this discussion. If he doesn't want to change something, I can do nothing anyway.

Best Regards
Ralf

I guess I got everything right.

You want someone else to do what you think would be beneficial for you and others. And you don't want to do anything about it. That is clear.

Just an observational note.
This discussion got unnecessarily overheated I think.

I didn't read the initial post as being aggressive, and in fact, objectively, it mirrors my own experience from a couple of years ago (when I played with PDF for a while). Maybe a bit direct ;) But we're all adults I hope...

It also does seem relatively clear that the OP is trying to say: that the out-of-the-box PDF profile should look 'nice(r)' (some version of 'nice', as a kind of advertisement). He's also asking if the idea is to play with the .yaml file (it was, last time I checked, but I was not initially sure either). He's also saying he doesn't feel like the best person to set any 'nicer' defaults. Fair enough.

I don't think he is even slightly impugning the legendary work that Dan and his team do to build and maintain Asciidoctor. The true vote on that is people using it, as the OP is.

I know what it is like to put out OS tools, specifications and much else, that took 10,000s of hours to create, often not paid properly, and to have people make pretty direct comments on them. I have been doing this for 20+ years within a global and particularly European community. I learned a few things:

* never take offence, it is rarely if ever intended. If someone is actually trying to offend, it will become obvious very quickly.
* the written word always appears more brutal than a f2f conversation; don't make negative assumptions, they are unlikely to reflect reality
* Dutch people are really direct! They are almost always smiling at the same time. You just can't see that in a written post.

I have no idea if Ralf is Dutch; I just mention it as a by now well-known funny point in our community: there really are differences across how Swedes, Dutch, French, Brits, Russians etc naturally communicate, and it took our members a bit of time to realise that. When some of our committees get together face-to-face, some people can't believe the personalities of people they assumed were offensive; in fact, most of it comes down to different senses of humour, and different cultural norms. British say please and thank you 10 times for 1 coffee; French only once, no small talk. In the US, I have ordered pizza in NY, where if you don't make up your mind fast enough, they start swearing at you, and in SLC, where they are so polite they practically give it to you, and every place between. I never met anyone in such circumstances who was trying to offend me.

I do hope this community can function in a similar good-humoured way, and make the most of everyone's contributions, with a minimum of negative assumptions.

As I said, he had valid points. But why not go further than forum posts and structure them as issues on github?

well there are all sorts of reasons people might not do that. Primarily I would say when people think that the issues to be raised would become clearer with some online discussion first, or they are just not sure of the status of a project or dynamics of a community. Noone likes to pollute somebody's project with junk issues. But I'm only guessing.

> well there are all sorts of reasons people might not do that.

I understand.

The thing is, there are a lot of stuff to be done on asciidoctor-pdf -- critical, major, minor.
All of it is in Github issues -- that is the primary source of what would be fixed, improved, changed as far as I understand.

Thus we can agree on "this particular feature is a must have" in online discussion and it is fine.
But there should be the one who will do the next steps. And the first step is an issue on github.

I actually think to work that kind of thing out, moving to Discourse would be an improvement, because it enables a much better representation of groups / areas of interest etc within a community. This nabble list, which is fine from a mailing list point of view doesn't really do this. With a better definition of groups, the core devs could shape the community better, and community members could connect more easily to development efforts, dev-oriented discussions and so on. Other kinds of users, testers etc would have dedicated groups.

This is our discourse instance, just to give you an idea of what it looks like.

Hello Ralf,

Here are the files that set the default theme in asciidoctor-pdf output.

https://github.com/asciidoctor/asciidoctor-pdf/tree/master/data/themes

I recommend that if you have changes you would like to make to the defaults, that you edit these files and create a merge request.

I am positive that zero people want the default theme to bring about feelings of dissatisfaction.
If you can back those changes with some recognized typography design reference, it will add weight to the request.