search

ggrossetie / asciidoctor-web-pdf

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

Project name clashes with asciidoctor/asciidoctor-pdf (Ruby) #125

Closed ThomasPrioul closed 8 months ago

ThomasPrioul commented 4 years ago

What happens if I have both this project and the Ruby pdf export project from asciidoctor installed globally on my machine? The first one found in the path will be used. Perhaps renaming the CLI script to asciidoctor-pdf.js (same as the actual repo name) would help? Like how asciidoctor.js can coexist with asciidoctor?

ggrossetie commented 4 years ago

We had some debate on the Asciidoctor.js CLI (based on Asciidoctor.js) and we've decided to use the same name. Previously, the binary was called asciidoctorjs but it was confusing.

For instance, the following was not working:

npx asciidoctor -v

Even though the npm module is called asciidoctor, the binary was called asciidoctorjs... why is that you could ask if you didn't know about Asciidoctor Ruby. I believe that it's pretty rare to install both Asciidoctor.js and Asciidoctor Ruby globally. And I can assume that if someone do that, then he must understand that he's using two implementations of the same project, one in Ruby and one in JavaScript. So he must decide which one he want to use. When in doubt, you can always type: asciidoctor -v or asciidoctor-pdf -v.

Having said that we might reconsider this decision for this project because unlike Asciidoctor.js, this project is not a transpilation of Asciidoctor PDF (Ruby). In other words, it's not the same code base. It's two distinct projects based on different technologies.

I don't really like the "js" suffix in a command line and I think it's more accurate to say that this project is based on web technologies. So maybe asciidoctor-web-pdf as suggested by @mojavelinux.

Summoning my peers for their valuable input 😉

//cc @oncletom @ahus1 @rdmueller @Ablu

Gosh naming is hard, who knew?! 😆

thom4parisot commented 4 years ago

It's only an issue if you install both packages globally. If you install both packages globally, I think the responsability of knowing which binary is called is on the user.

Global binaries installed with npm can be retrieved with ls $(npm config get prefix)/bin.

Another thing I see is adding an extra binary name (as @asciidoctor/cli does) to provide 2 binary names (asciidoctor and asciidoctorjs to pursue on the previous example).

ggrossetie commented 4 years ago

I just renamed the repository and I've added asciidoctor-web-pdf as an alias. With https://github.com/Mogztter/asciidoctor-web-pdf/pull/243 both asciidoctor-pdf and asciidoctor-web-pdf are valid bin names.