Libelektra: How does updating man pages work?

[markus2330]

Describe what you wanted to do

Update a man page doc/man/elektra-libs.7 after modifying src/libs/README.md.

Describe what you expected

rm -r doc && make man will update the man page or some description describing the process.

Describe what actually happened

man page is not updated, despite of having ronn installed.

It also seems that doc/help/CMakeLists.txt installs man pages twice: once within generate_manpage, once with FILES_MATCHING PATTERN.

System Information

• Elektra Version: master

[markus2330]

It seems to update the man pages after a rebuild with make, but not with make man. Is this intended?

[sanssecours]

It seems to update the man pages after a rebuild with make, but not with make man. Is this intended?

Nope. Honestly, I never use another target than the main one or test. I will take a look.

[sanssecours]

It seems to update the man pages after a rebuild with make, but not with make man.

I can not reproduce this bug. Here is what I did:

1. Clean the build directory

2. Configure Elektra

   mkdir build
   cd build
   cmake ..
   make man
   

3. In the last step make produced the man pages in the folder build/doc/help and copied them to doc/man. Since the man pages are identical git show no changes.

4. Modify one of the man pages. I replaced summarise in doc/help/elektra-bootstrapping.md with the American English spelling of the word summarize.
5. Run make man again
6. Git now shows the updated man page doc/man/elektra-bootstrapping.7
7. Undo the changes to doc/help/elektra-bootstrapping.md
8. Run make man again
9. Git shows no changes since the last step overwrote the modified version of doc/man/elektra-bootstrapping.7

Do the steps above work for you too?

[sanssecours]

It also seems that doc/help/CMakeLists.txt installs man pages twice: once within generate_manpage, once with FILES_MATCHING PATTERN.

As far as I can tell this is not the case since generate_manpage will only be called when ronn is available:

find_program (RONN_LOC ronn)

if (RONN_LOC)
   # generate_manpage(…)
else ()
    if (INSTALL_DOCUMENTATION)
        install (DIRECTORY "${MAN_PAGES_DIR}/" DESTINATION share/man/man1 FILES_MATCHING PATTERN "*.1")
        install (DIRECTORY "${MAN_PAGES_DIR}/" DESTINATION share/man/man7 FILES_MATCHING PATTERN "*.7")
    endif (INSTALL_DOCUMENTATION)
endif ()

. I could be wrong though. Could you please explain why you think that the build system installs the man pages twice?

[markus2330]

I can not reproduce this bug.

Thanks for looking into it. I think the problem was that I removed parts of the build tree (I did this because doxygen needs this to rerun). It works perfectly when done as you describe. I removed the question tag as the question is answered.

Could you please explain why you think that the build system installs the man pages twice?

generate_manpage implemented in cmake/Modules/LibAddMacros.cmake already installs the man pages (line 539).

We should now fix generate_manpage to also install docu even if RONN_LOC is false. (Because the man pages are available nevertheless) and this does not only affect doc/help but also all other man pages such as the one generated in src/libs/CMakeLists.txt.

Why do you think we need lines 24+25 in doc/help/CMakeLists.txt? What is different to the help man pages compared with the other places that use generate_manpage? Actually all generate_manpage except the src/libs/CMakeLists.txt are for tools. I agree if you want to remove the generate_manpage from src/libs/CMakeLists.txt, it is a bit strange that it is used there.

[sanssecours]

I also tried your example from above. It also works. You might have to save src/libs/README.md twice though.

Updating the man pages will work if you modified the input file (.md), after your last invocation of the build system. This is not always the case though. I will take a closer look at the problem now.

[markus2330]

I will take a closer look at the problem now.

Thank you. But I do not think this is important, we should rather look into the installation problem and the other more important build+test problems.