search

ggrossetie / asciidoctor-web-pdf

Convert AsciiDoc documents to PDF using web technologies
https://asciidoctor.org
MIT License
448 stars 92 forks source link

How we should distribute this CLI #20

Open ggrossetie opened 5 years ago

ggrossetie commented 5 years ago

What I have in mind is something like:

npm i @asciidoctor/cli-pdf @asciidoctor/pdf-generator-default

Then you can convert a document to a PDF:

asciidoctorjs-pdf document.adoc

We could also publish other generator:

npm i @asciidoctor/pdf-generator-cheatsheet
asciidoctorjs-pdf document.adoc --generator cheatsheet

Of course it will be still possible to use local "generator":

asciidoctorjs-pdf document.adoc --generator ./generator.js

Please note that currently a generator is nothing more than a template converter but we could decide to introduce more features in the generator.

ping @oncletom @mojavelinux @matklad

matklad commented 5 years ago

SGMT! Though I think using a custom generator will be a common (most common perhaps?) approach, so workflow of coping and modifying an existing generator should be smooth as well.

That probably is better achieved with a documentation:

If you want fine-grained tweaking of the resulting HTML, copy-paste an existing generator.js to your project, modify it for your needs and run with --generator ./my-generator.js

mojavelinux commented 5 years ago

Overall, I like where this is going.

I'm not sure generator is the right word here. But I'm not sure what it would be. Naming it converter would be overloaded this this is already a converter. Perhaps producer or composer?

I think the default producer/composer should be installed by default just to make it easy to get started. It doesn't hurt to be there.

I think the CLI name is getting a little confused/convuloted. asciidoctorjs-pdf reads very awkwardly. Perhaps asciidoctor-pdf.js or even just asciidoctor-pdf (with an understanding that it's unlikely people will be using both the Ruby version and this one). The alternative would be to rename this project to asciidoctor.js-pdf. Then at least asciidoctorjs-pdf would be more logical.

mojavelinux commented 5 years ago

I'd name the package @asciidoctor/pdf-cli if you're going to use that scheme.

thom4parisot commented 5 years ago

I'm wondering about this:

$ npm install -g @asciidoctor/cli 
$ asciidoctor -b pdf source.adoc -o dest.pdf
> Error: unknown backend.
> You might want to run the following command to support this backend:
> npm install @asciidoctor/backend-pdf

$ npm install -g @asciidoctor/backend-pdf
$ asciidoctor -b pdf source.adoc -o dest.pdf
$ asciidoctor -b pdf --generator ./my-generator.js -o dest-alt.pdf
ggrossetie commented 5 years ago

Lot of ideas! :grinning:

Official backends

asciidoctor -b pdf source.adoc -o dest.pdf
> Error: unknown backend.
> You might want to run the following command to support this backend:
> npm install @asciidoctor/backend-pdf

For now ignore the naming, I'm just focusing on the behavior. I really like this idea and it makes perfect sense to me. The user may not fully understand what is included or not but the CLI can understand the intent and thus suggest a resolution.

In other words, it means that the CLI knows a set of "official" backends:

And if the user requests an "official" backend (without explicitly using the --require option) then we should try to load this "official" backend. If it fails, we should suggest to install the package using npm.

Should we create an issue in https://github.com/asciidoctor/asciidoctor-cli.js/ to continue the discussion ?

Add a --composer option to the Asciidoctor CLI

Again ignore the naming. The question is should we add a --composer option to the Asciidoctor CLI. Does it make sense in other converters ?

Add a --watch option to the Asciidoctor CLI

One feature that is currently missing in Asciidoctor CLI is --watch. Should we add this feature ?

$ asciidoctor source.adoc -o dest.pdf --watch

Will watch "source.adoc" for changes. It may be a bad idea because users might expect the --watch to be smart and also watch for included files or resources (images...). So in the end it might be hard to provide something useful without knowing the workspace.

Another idea is to configure --watch:

$ asciidoctor source.adoc -o dest.pdf --watch 'includes/**.adoc' --watch 'images/*'

Do we need a CLI for Asciidoctor PDF ?

I might be wrong but the following command implies "do we really need a dedicated CLI for Asciidoctor PDF ?":

$ asciidoctor -b pdf source.adoc -o dest.pdf
> Error: unknown backend.
> You might want to run the following command to support this backend:
> npm install @asciidoctor/backend-pdf

After all asciidoctor-pdf is just a shortcut for asciidoctor -b pdf right ?

Naming!

A global (and first) decision is should we use scoped packages (ie. @asciidoctor prefix) for "official" packages ?

If we keep the Asciidoctor PDF CLI (see above), define the name of the binary. Make sure that this name is consistent with the Asciidoctor CLI (and potential others CLI).

There's more questions about naming but I think we should first answer the questions above.

ggrossetie commented 5 years ago

I will create issues in the Asciidoctor.js CLI repository so we can discuss each issue separately :wink:

ggrossetie commented 5 years ago

Related issues: https://github.com/asciidoctor/asciidoctor-cli.js/issues/43 https://github.com/asciidoctor/asciidoctor-cli.js/issues/42 https://github.com/asciidoctor/asciidoctor-cli.js/issues/41

:speech_balloon: :bulb: Feel free to jump in and share your ideas and opinions