Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
sync --help output w/ manpage #177
referenced this pull request
Apr 7, 2017
@pskocik if you feel like contributing more to re2c and get tired of sending pull requests, I could give you github access. All your patches so far have been flawless.
I myself make changes in the
I think using the rsts from the gh-pages-gen branch is a more viable approach towards deduplicating the docs. It's easier, because the options sections of the manpage (or the --help page, which is basically the same thing sans formatting) is comprised of multiple rsts (the manpaged patched to
Anyway, that's what I've done experimentally in my fork now. I've also pruned the original gh-pages-gen/src/manual off of the pngs before moving it to master, and the buildscript now lazily regenerates the pngs from the text.
The last thing I think should be done as part of refactoring the docs should be to make the master/re2c build script generate the --help page from the manpage. Unfortunately, I don't really know a good way to make autotools do that (IDK autotools well). It could run something like the oneliner from my last patch,
although that would need to be piped to a throw-away text-to-c(++) serializer, which could be as simple as:
Again, I'm a little helpless as to how to integrate something like this with autotools well.
As for my contributions, I only wanted to study and fix the docs. I don't plan on contributing much beyond this.
I think it's better if
Integration with build system is not much different from other preprocessors. We already use two of them: bison (for the parser) and re2c (for the lexer, configuration parser and parser of options).
The generator itself could be written in C++ (but then it has to be built) or in POSIX shell, I think. C++ program has the advantage that it can run on Windows, but one should be careful with crosscompilation. POSIX shell is portable with the exception of Windows, but the build system doesn't support Windows anyway. I probably prefer shell script (it is simpler).
All the autogenerated files should have backup copies in
You are welcome in any case. :)
Feel free to reject my proposed changes, but take a look at it at least, please. I think the setup is pretty simple and robust. What I've done is I've moved the manual directory (after removing the pngs) from gh-pages-gen to re2c/doc/manual and I'm including those rsts inside manpage.rst.in which shrank to this
This adds nothing to the build system in master, but I have expanded the build script on gh-pages-gen
I think it is simple and deduplicates the documentation well.
The build system on master could additionally use something like:
to generate a
The first part (syncing online docs with manpage) looks good, except for the following:
If we agree on these two issues, I would gladly accept this part.
Now for the second part (syncing help with manpage).
If you don't feel like digging in
I've implemented part 1. As for part 2, please do the reconfiguration of Makefile.am. (I don't have much of an incentive to learn autotools. :D)
I don't know how to convert text to a c array with a shell script portably, but we could immediately use the above C program with a specifiable manpage, unless you have a better alternative.