'Cross-platform' documentation with a lot of file system path

Previous Topic Next Topic
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view

'Cross-platform' documentation with a lot of file system path


I have to write some documentation that contains a lot of file system paths. The instruction are cross-platform, so the output must work both on Windows and on Linux.
Since the only difference between the documentation for Windows and for Linux is the use of \ or /, i would like to avoid having to maintain multiple copies of the documentation (one for each platform).
I am therefore looking for a way to write a single generic document.

In some cases, I can simply use attributes, and define the paths in 'ifeval' blocks, like this for example:
ifeval::["{IBM_OS_TYPE}" == "UNIX"]
:MY_PATH: /tmp
ifeval::["{IBM_OS_TYPE}" == "WINDOWS"]
:MY_PATH: C:\Temp

This is fine until, in a later section of the document, I need to do something such as:
Considering the number of paths I am dealing with, I cannot have ifeval block everywhere.

Another alternative would be to define a 'separator' attribute:
:sep: \
And then use it like this:
Unfortunately this quickly makes the source very difficult to read ({MY_PATH}{sep}{anotherPath}{sep}{andSoOn}.

The easiest solution (for me) would be to use forward slash everywhere. After all, this also works on Windows. That's also unfortunately not an option, I must produce backslashes for Windows.

Any idea on how to nicely tackle this problem? It would be nice to be able to call a user defined function, such as convert({MY_PATH}), which would replace all the / with \, but I don't know if this is possible.

Reply | Threaded
Open this post in threaded view

Re: 'Cross-platform' documentation with a lot of file system path

I think that I managed to answer this question myself: simply define and use a macro! Sorry if the initial question sounded silly, I am pretty new to this...

So, I now have a custom macro that I can use like this:
The macro outputs the path in different format depending on which attributes are set or passed to the macro.

But this leads a new questions about macros in general.

First, let me provide a bit of context: I will have to distribute the source documentation (adoc files) to various people. I cannot just provide the generated .html or .pdf.
So an important problem is how can I distribute the macro with the document, and make it easy for other people to use it, assuming that they don't all use the same tools.

So, questions:

1. is it possible to embed the macro in source of the document itself or to reference it somehow in the headers? This would by far be the best/cleanest solution.

2. if different people use different flavors of asciidoctor (ruby, javascript, etc.), does it mean that the macro must be translated in each language? I assume that the answer is yes, but it would be very nice to have a common way to define macros, one that would be language independent.

3. what about the different tools used for preview: browser plugin, Atom or Visual Studio plugins, etc. Can they work with custom macros? Those are mostly using asciidoctor.js => is it possible to embed the macro into the plugin's code easily?

4. assuming that there is no easy way to provide a macro that would be easy to use regardless of the language and tools used by other people, what would be the best solution to provide a portable way to generate an output document (lightweight if possible)? The idea is that I could distribute, with the source documentation, a tool already customized and configured to use the macro to generate the final output.

5. any pointers to some documentation related to the questions above? I haven't been able to find much...

I have the feeling (but I hope that I am mistaken) that asciidoctor is mostly meant to be used to distribute and publish the final output. Sharing the source seems to be tricky as soon as extensions are involved, because of the dependencies on the tooling. Is this correct?

Thanks a lot!