Better docs for CLI args?

[polarathene]

Athena mentions being a drop in replacement for wkhtmltopdf despite the change from an outdated webkit to blink. I'm aware I can use --help for a list of commands, are they meant to be similar to wkhtmltopdf? They seem different(the supported ones). The CLI help isn't too clear about some of the accepted values.

    -h, --help                   output usage information
    -V, --version                output the version number
    --debug                      show GUI
    -T, --timeout <seconds>      seconds before timing out (default: 120)
    -D, --delay <milliseconds>   milliseconds delay before saving (default: 200)
    -P, --pagesize <size>        page size of the generated PDF (default: A4)
    -M, --margins <marginsType>  margins to use when generating the PDF (default: standard)
    -Z --zoom <factor>           zoom factor for higher scale rendering (default: 1 - represents 100%)
    -S, --stdout                 write conversion to stdout
    -A, --aggressive             aggressive mode / runs dom-distiller
    -B, --bypass                 bypasses paywalls on digital publications (experimental feature)
    --proxy <url>                use proxy to load remote HTML
    --no-portrait                render in landscape
    --no-background              omit CSS backgrounds
    --no-cache                   disables caching

• I saw in another issue that zoom doesn't really have an effect or one of the expected effects(browser zoom), presumably a floating point value.
• pagesize I haven't looked into as A4 is fine, but is there a way to list available values?
• debug, not sure what this does, I tried it and didn't really see anything.
• margins, this is the one I'm interested in. I'm not sure how these are meant to be defined, I've seen standard and none as values but there is no docs/examples elsewhere or a way to find out the value config? I want to set differing horizontal/vertical margins.

[MrSaints]

I think it's fair to say that there needs to be a lot of work done on improving the documentation, and correcting the descriptions (I was never really a fan of it). I've already triaged these tasks.

• For printing, zoom has no visual impact (useful for hacking the DPI though). This is the same for Chromium;
• For page size, the following options are currently available: A3, A4, A5, Legal, Letter, Tabloid. Although, it should probably be updated to support custom sizes too;
• For debug, the Electron browser window will be shown instead of being hidden (since this CLI app is not really / truly headless), so this is mostly useful if you want to see how the page is loading up. This won't work inside Docker, unless you mount your display driver (since it is using Xvfb) or run athenapdf outside of Docker;
• For margins, the following types are currently supported: standard, minimal, none.

In theory, you can override the margins via CSS (see @page at-rule).

[polarathene]

For printing, zoom has no visual impact (useful for hacking the DPI though). This is the same for Chromium;

If you can hack the DPI that way, it could change the layout based on DPI media queries?(supposedly other elements like picture for providing retina/mobile assets)

For debug, the Electron browser window will be shown instead of being hidden (since this CLI app is not really / truly headless)

Definitely should be added to the docs, I was under the impression I should be running via Docker. Not sure if it was mentioned that I could install/use it another way(just NPM install?).

For margins, the following types are currently supported: standard, minimal, none.

The browsers print to pdf supports setting margins, is there no exposed API for you to modify these individually? What does standard/minimal translate to? I'll look into the CSS rule you mentioned, hopefully that works if Athena is unable to support custom margins.

[bersling]

In theory, you can override the margins via CSS (see @page at-rule).

That sounds interesting, how would I do that? I tried:

@media print {
    @page {
        margin: 0;
    }
}

but it still had some margin.

[polarathene]

Some browsers support the CSS differently. I found quite a few did not support some print properties that well when printing to PDF, possibly due to some other CSS rules, I did not confirm.

I think for Chrome you need to choose custom margins or something to let it use the margins your CSS set, verify with Chrome print. Athena probably has to do something similar if Chrome can use the ones you specify.

[bersling]

I just checked, on chrome print I get zero margins while with athena I still have the margins using the above css.

[MrSaints]

@bersling If you don't mind, can I have a look at the HTML/CSS you are using? What you did should work, and I've tried it out on master.

[bersling]

Hi, thanks a lot for the offered help. I just checked again and it worked. It was a caching problem, sorry for that!

[teohhanhui]

If athenapdf is a "drop-in replacement" for wkhtmltopdf, it means it should have CLI compatibility, such that you can simply replace the wkhtmltopdf binary with the athenapdf binary, and things should just work. But that's clearly not the case. So the description is misleading.