Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Dear group,
we embed screenshots in our software documentation like this: == Example section This section explains what we see in this screenshot: image::some_screenshot.png[screenshot, width=90%, align="center"] Rest of the section text, explaining… Unfortunately, most of our screenshot images have a white background and no inherent border of their own. Using the HTML output with the default stylesheet, this results in screenshots whose dimensions cannot be noticed, as white matches white page background. Some solutions are obvious: 1. use a custom stylesheet e.g. for adding a box-shadow to the screenshot images, 2. wrap the screenshot image inside an example block: ==== image::some_screenshot.png[screenshot, width=90%, align="center"] ==== Solution 1 looks remarkably complex (stylesheet factory, giving up the wonderful convenience of the default stylesheet…) considering that we would like to only add a single-line CSS rule… Both solutions 1 and 2 raise the question how "compatible" this is with other-than-HTML output: custom CSS obviously doesn't help with PDF or EPUB, wrapping in an example block may or may not be desirable in PDF, EPUB, … That is, are these reasonable approaches for markup for screenshots, also considering PDF or EPUB or … output? Can we do better? The second problem: the "width=90%" with asciidoctor-pdf and asciidoctor-latex seems to generate images that are 90% of one inch wide (or are very small at least, e.g. thumbnail size) rather than 90% of page width. How can we approach this? Best regards, Carsten |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
On Mon, Feb 13, 2017 at 8:57 AM, Carsten [via Asciidoctor :: Discussion] <[hidden email]> wrote:
That's what the docinfo file is for. You can add a single CSS rule. See -Dan |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
In reply to this post by Carsten
On Mon, Feb 13, 2017 at 8:57 AM, Carsten [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Please see the pdfwidth attribute in Asciidoctor PDF. It supports a wide variety of units: |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
In reply to this post by mojavelinux
Hi Dan,
many thanks for your help! This works well, but only if the suffix of the input document is `.adoc`. With `example.adoc.txt`, I can only get the shared `docinfo.html` to work, but not the private `example-docinfo.html`. There is no diagnostic output in this regard like "private docinfo file not found", even if I run asciidoctor with the -v flag. Is this a matter of the proper document suffix or am I doing anything wrong? |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
I strongly recommend using a recognized file extension. Otherwise, certain features, such as docinfo file resolution, don't work properly. There isn't a warning when a docinfo isn't found because the file is always optional. However, when we add logging to Asciidoctor, this could be a useful debug message. Cheers, -Dan On Feb 15, 2017 11:15, "Carsten [via Asciidoctor :: Discussion]" <[hidden email]> wrote: Hi Dan,many thanks for your help! ... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Hi Dan,
thanks! I used .adoc.txt as the extension because programs that are unaware of AsciiDoc files, but know .txt files, can still deal with these files, e.g. preview panes in file explorers. Follow-up question: Is there a similar technique for adding a border to images in PDFs created with asciidoctor-pdf? According to the user manual, docinfo files don't apply to PDFs. I've seen https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc, but it seems to imply that a complete standalone theme must be made. I might be able to work-around this via a script that manipulates the image files on disc, that is, loads each image, adds a border, saves them again, runs asciidoctor-pdf and eventually restores the original images. But I hope there is a better way to do this without creating a complete YAML theme? Best regards, Carsten Am 06.03.2017 um 03:10 schrieb mojavelinux [via Asciidoctor :: Discussion]: > I strongly recommend using a recognized file extension. Otherwise, > certain features, such as docinfo file resolution, don't work properly. > > There isn't a warning when a docinfo isn't found because the file is > always optional. However, when we add logging to Asciidoctor, this could > be a useful debug message. > > Cheers, > > -Dan |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
I used .adoc.txt as the extension because programs that are In that case, I recommend using .txt, which is a recognized extension (not .adoc.txt). But what I've done is simply register the .adoc extension with my file explorer so that it knows how to handle it. Thanks to the numerous add-ons in the Asciidoctor ecosystem, many tools, particularly Chrome and Firefox, now recognize the .adoc extension and provide a preview.
Not yet. See https://github.com/asciidoctor/asciidoctor-pdf/issues/767. I might be able to work-around this via a script that manipulates the image files on disc, that is, loads each image, adds a border, saves That's what I would do. and eventually restores the original images. If you process all images into a "build" directory, you don't have to restore the originals. Just update the imagesdir attribute to point to the build directory. (You do have to copy all images there, passing them through your filter if they are screenshots). But I hope there is a better way to do this without creating a If you are going to use Asciidoctor PDF for anything long-term, I highly recommend creating a custom theme. Otherwise, you are always going to be stuck with the defaults and your PDF will look like every other one created. The default theme is supposed to be an example. Good luck! -Dan Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Thank you very much!
:-) Best regards, Carsten |
Free forum by Nabble | Edit this page |