On 9/25/21 9:59 AM, Gerald Combs wrote:
On 9/25/21 1:17 AM, Jaap Keuter wrote:
Hi,
In reference to https://gitlab.com/wireshark/wireshark/-/merge_requests/4294
What is supposed to happen to the man pages themselves? Will they now be generated from the AsciiDoc files? I think I’m missing the point to this change.
The man pages themselves would be generated using Asciidoctor's man page backend[1]. The primary advantage of the change is that we would use the same markup for all of our documentation, but this would also make it easier to include the Wireshark version if needed and other things that POD doesn't directly support.
The MR in its current form should definitely not be merged. I intentionally left the .pod versions of each man page in place in order to make it easier to compare with the .adoc version. Assuming no one strongly objects to this, the next steps would be
- Add a ASCIIDOCTOR2MAN macro to cmake/modules/FindAsciidoctor.cmake.
- Make the necessary changes doc/CMakeLists.txt.
- Remove the .pod files
It would probably make sense to consolidate the man pages and guides into the same directory as well.
[1]https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/
The MR should be ready to go now, and I plan on merging it tomorrow. Note that this will Asciidoctor a requirement for packaging.