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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Ralf Jahns
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
Reply | Threaded
Open this post in threaded view
|

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

mojavelinux
Administrator
I know it may no be your intention, but I find your comments to be extremely insensitive. I dedicate a very large portion of my life to maintaining Asciidoctor, much of which has been focused on Asciidoctor PDF over the past year. I work very hard to make it look the best I can. If you don't like the result, you're free to customize the theme using the theming system or extend the converter to make it suit your fancy. It's open source. But you don't have to put down the work of others to get what you want.

You aren't going to win any friends here with your aggressive remarks. This is open source and you need to respect the process, contract, and the people who work on it if you want to be welcomed in this community.

Thank you for understanding,

-Dan

On Fri, Jan 24, 2020 at 1:41 PM Ralf Jahns [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/Why-does-the-default-output-of-asciidoctor-pdf-look-so-ugly-tp7536.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

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

habamax
In reply to this post by Ralf Jahns
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.


Reply | Threaded
Open this post in threaded view
|

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

Ralf Jahns
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





Reply | Threaded
Open this post in threaded view
|

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

habamax
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?

Reply | Threaded
Open this post in threaded view
|

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

Ralf Jahns
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

Reply | Threaded
Open this post in threaded view
|

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

habamax
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.



Reply | Threaded
Open this post in threaded view
|

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

habamax
In reply to this post by Ralf Jahns
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.
Reply | Threaded
Open this post in threaded view
|

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

Ralf Jahns
This post was updated on .
In reply to this post by habamax
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
Reply | Threaded
Open this post in threaded view
|

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

habamax
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.
Reply | Threaded
Open this post in threaded view
|

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

wolandscat
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.
Reply | Threaded
Open this post in threaded view
|

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

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

Reply | Threaded
Open this post in threaded view
|

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

wolandscat
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.
Reply | Threaded
Open this post in threaded view
|

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

habamax
> 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.
Reply | Threaded
Open this post in threaded view
|

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

wolandscat
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.
Reply | Threaded
Open this post in threaded view
|

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

bwklein
In reply to this post by Ralf Jahns
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.