Dealing with screenshots

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Dealing with screenshots

Carsten
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

Reply | Threaded
Open this post in threaded view
|

Re: Dealing with screenshots

mojavelinux
Administrator

On Mon, Feb 13, 2017 at 8:57 AM, Carsten [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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…

That's what the docinfo file is for. You can add a single CSS rule. See


-Dan


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

Re: Dealing with screenshots

mojavelinux
Administrator
In reply to this post by Carsten

On Mon, Feb 13, 2017 at 8:57 AM, Carsten [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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?

Please see the pdfwidth attribute in Asciidoctor PDF. It supports a wide variety of units:


-Dan


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

Re: Dealing with screenshots

Carsten
In reply to this post by mojavelinux
Hi Dan,

mojavelinux wrote
That's what the docinfo file is for.
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?
Reply | Threaded
Open this post in threaded view
|

Re: Dealing with screenshots

mojavelinux
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,

mojavelinux wrote
That's what the docinfo file is for.
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?



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Dealing-with-screenshots-tp5271p5282.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: Dealing with screenshots

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

Re: Dealing with screenshots

mojavelinux
Administrator
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. 

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.

Is there a similar technique for adding a border to images in PDFs
created with asciidoctor-pdf?

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 
them again, runs asciidoctor-pdf

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 
complete YAML theme? 

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

Re: Dealing with screenshots

Carsten
Thank you very much!

:-)

Best regards,
Carsten