search

asciidoctor / asciidoctor-intellij-plugin

AsciiDoc plugin for products on the IntelliJ platform (IDEA, RubyMine, etc)
https://intellij-asciidoc-plugin.ahus1.de/
Apache License 2.0
356 stars 145 forks source link

Add support to convert AsciiDoc to DOCX format #1074

Closed ahus1 closed 2 years ago

ahus1 commented 2 years ago

Why the new feature should be added

A user should be able to convert AsciiDoc to the DOCX format to be able to open it for example in OpenOffice or Microsoft Word.

How the new feature should work

Next to the HTML and PDF buttons there should be a DOCX button that the user would click.

The currently open document will be converted to DocBook, which is then converted to DOCX using Pandoc. Pandoc will be automatically downloaded.

ahus1 commented 2 years ago

The next release will include this for Windows and Linux as it has been tested there. Test for macOS is pending, and it will be activated for macOS only after such a test.

ahus1 commented 2 years ago

This is now available in pre-release 0.37.24.

Docs are available here: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/creating-docx.html

The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

RayOffiah commented 2 years ago

Hello.

I've installed the plugin (0.37.24), but I'm not seeing the DOCX button

I'm running on macOS Monterey and IntelliJ IDEA.

ahus1 commented 2 years ago

Hi @RayOffiah - thanks for reaching out and your interest in testing it.

As it is not supported on macOS yet, it is hidden behind a feature flag until it has been tested.

To see the button you'll need to enable the internal mode, see Enabling the internal mode for the IDE in the JetBrain's IDE documentation.

Once you enabled this mode and restarted your IDE, you should see DOCX in your toolbar:

image

Once you click "DOCX", it should create first an XML file (DocBook) in the current file's folder. Then it creates DOCX file and opens it with the associated application (for example Microsoft Word of LibreOffice).

If it doesn't work, we'll need to debug this, and I'll have lots of questions. A picture what you see would be a nice start if it doesn't work (and also if it works).

Thanks!

RayOffiah commented 2 years ago

Yep, got the button now.

I'm clicking it.

Nothing seems to happen.

Right okay, the test.xml file has appeared in the folder. Just needs a click away to update the file window by the looks of it.

The Docbook xml file is generated and it looks fine; no DOCX file though.

ahus1 commented 2 years ago

Did you get a small red notification icon at the lower right corner of your IDE?

image

If you did, please click on it and send a screenshot, and also click on the "Report" button. If the exception is correctly classified as a problem with the AsciiDoc plugin, the "Report" button will send this to my inbox. It might contain additional information about an exception that helps me to analyze the problem.

To analyze this further, please send me the log file of your IDE via email. Retrieve the log file via "Help | Show Log in Explorer" (might be a different menu item on macOS). Then send the file via email to the email address you see when clicking on my profile on GitHub. It might contain more information that I need to analyze the problem.

Let's hope that yields some additional information. If not, the next best thing I can think of is pairing up for a screen sharing session. Let's see.

Thanks!

RayOffiah commented 2 years ago

Ah, yes. I have this:

/Library/Caches/JetBrains/IntelliJIdea2022.2/download-cache/asciidoctor-intellij-plugin/pandoc-2.18/bin/pandoc error=13, Permission denied

ahus1 commented 2 years ago

Could you please send a screen shot, or copy the text? I'd be interested in the stacktrace that would show me the location of the code where this happened.

Does that file listed above exist in the file system? It would be interesting to know what you find in and below the folder "pandoc-2.18".

Thanks!

RayOffiah commented 2 years ago

Yeah, the full line reads:

Cannot run program "/Users/raymond/Library/Caches/JetBrains/IntelliJIdea2022.2/download-cache/asciidoctor-intellij-plugin/pandoc-2.18/bin/pandoc" (in directory "/Users/raymond/projects/asciidoctor-external-callout-js"): error=13, Permission denied

I've had a quick look, and the file is definitely where it's supposed to be. Hold on, I'll see if I can sort out a stack trace

ahus1 commented 2 years ago

Hm, maybe you could try to make the file executable, and give it another try - not sure how to do that on macOS, I'd try a chmod +x pandoc on Linux.

RayOffiah commented 2 years ago

I was just looking that up :-)

ahus1 commented 2 years ago

Ok, just had a look, this is a simple error message, probably together with the text "Error creating DOCX from AsciiDoc file" and that wouldn't have a stack trace.

Let's see if the executable permissions change something. I'll automate that in the next upcoming pre-release.

RayOffiah commented 2 years ago
Screenshot 2022-06-25 at 15 27 20

Perfect!

RayOffiah commented 2 years ago

Yes, aside from the permissions it works!

This is game changing!

ahus1 commented 2 years ago

Nice! Let me prepare another pre-release that should include the "make executable"...

RayOffiah commented 2 years ago

Incidentally, the plugin works fine with the new IntelliJ look and feel.

RayOffiah commented 2 years ago

Okay, I have to go and see Top Gun :-(

When I get back, I'll scrub the plugin and the cache directory, and then reload it from scratch from the IntelliJ prerelease repo.

ahus1 commented 2 years ago

Have fun! I'm also about to leave...

RayOffiah commented 2 years ago

This is great work!

ahus1 commented 2 years ago

There is now pre-release 0.37.25 available, this should set the executable permission for the pandoc file automatically on macOS.

This new pre-release still needs the internal mode enabled as described above on macOS until this is fully tested..

To try this out:

I'd be happy to hear back from you once your time permits. Have fun watching Top Gun! Please, no spoilers here...

The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

RayOffiah commented 2 years ago

Yep, working perfectly now. Cache reinstalled and works straight away.

ahus1 commented 2 years ago

Thank you very much, your testing revealed a bug that has now been fixed. It also gives me the confidence to remove that flag for macOS that would then make it generally available for macOS.

I plan to for a regular release (non-pre-release) next week.

By the way: did you test on an Intel Mac or a M1?

RayOffiah commented 2 years ago

Glad to help, and once again, thanks again for such a great plugin!

Oh, it was an Intel Mac.

ahus1 commented 2 years ago

With pre-release 0.37.26 this is now generally available for macOS. Thanks again to @RayOffiah for testing this on macOS and helping me to find bugs.

If you've enabled the internal mode, I recommend to disable it once you've installed the latest version of the plugin, as that setting might affect other parts of the IDE as well.

The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

KLynn2019 commented 2 years ago

I tested it out and...this may be what finally tips my team over to IntelliJ. 🙂 Great work!

The only downside really isn't with the plugin but with Pandoc's limited number of styles in reference.docx. Our department template is much more detailed...but it's nothing a VBA macro can't fix.

ahus1 commented 2 years ago

@KLynn2019 - this makes me both happy and shiver that "we support DOCX export" can achieve something like that. Maybe #953 (convert AsciiDoc to Markdown) might shift it even more?

Please let me know if the approach to place the reference.docx just somewhere in the project is helpful, it was a random attempt to make it as frictionless as possible.

As you mention it here: It seems to me that you've read the docs when trying out the feature (not everyone does that) and it that you've been "rewarded" with the discovery of a built-in feature. I'd be happy to hear ideas to make it even more discoverable without reading the docs.

KLynn2019 commented 2 years ago

@ahus1 I don't know how many folks used or are using Word as...um...intensely as we have. Prior to switching to AsciiDoc we created all of our online help and PDFs using Word documents as our source. Until recently we were publishing DOCX files on our content management system as well.

I think the location of reference.docx makes sense. Would it be possible to identify an AsciiDoc file that's in an Antora repository and give the user the option to save the DOCX file elsewhere? Most of the team gets it (don't just dump random files in the Antora repository if they're not explicitly used by Antora to create sites), but it wouldn't hurt to remind them.

Also, I assume the XML file can be deleted entirely?

ahus1 commented 2 years ago

Also, I assume the XML file can be deleted entirely?

Thanks for pointing this out, this has now been fixed in 0.37.27.

Would it be possible to identify an AsciiDoc file that's in an Antora repository and give the user the option to save the DOCX file elsewhere?

I'll move this to a new issue.