Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sync --help output w/ manpage #177

Merged
merged 1 commit into from Apr 8, 2017

Conversation

@pskocik
Copy link
Contributor

commented Apr 7, 2017

+ set output width to 80
+ make help output go to stdout rather than stderr

fixes #176

sync --help output w/ manpage
    + set output width to 80
    + make help output go to stdout rather than stderr

@skvadrik skvadrik merged commit 107a30b into skvadrik:master Apr 8, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@skvadrik

This comment has been minimized.

Copy link
Owner

commented Apr 8, 2017

@pskocik, thanks!
Especially thank you for leaving that useful command in comment.

@skvadrik

This comment has been minimized.

Copy link
Owner

commented Apr 8, 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 devel branch most of the time (except applying patches and releasing), so there probably won't be any conflicts between us. We can make an agreement that you push small changes to master and big/controversial changes to some other branch.

@pskocik

This comment has been minimized.

Copy link
Contributor Author

commented Apr 8, 2017

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 .. include:: the rsts from gh-pages-gen), so if you wanted to start there, you'd need to split rather than concatenate, and concatenation (.. include:: somefile.rst from manpage.rst.in) is easier than splitting. I think that for robustness, gh-pages-gen/src/manual could go from gh-pages-gen to master/re2c/doc and the build script of the website could pull it back with git worktree.

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,

MANWIDTH=88 PAGER=cat man $buildir/doc/re2c.1| sed -n '/^OPTIONS/,/^INTERFACE/ { s/^       //; /^[ -]/ p;}' 

although that would need to be piped to a throw-away text-to-c(++) serializer, which could be as simple as:

#include  <stdio.h>
int main(int c, char **v)
{
    int  ch; FILE *f = c <= 1 ? stdin : fopen(v[1],"r");
    puts("namespace re2c { extern char const help_string [] = { ");
    while (EOF != (ch=fgetc(f)))
        printf("'\\x%x',\n", ch);
    puts("}; }");
    return (!ferror(stdin) && !ferror(stdout)) ? EXIT_SUCCESS : EXIT_FAILURE;

}

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.

@skvadrik

This comment has been minimized.

Copy link
Owner

commented Apr 9, 2017

I think it's better if .rst files were autogenerated from .h file, so that source files remain as simple and self-contained as possible. What you suggest (generate .h from .rst) keeps the source files self-contained, but it adds complications into the main build system. I'm convinced that all the complexity should be on the documentation side. Synchronization with documentation should not affect source files.

That .h file could be split in two (options and warnings).

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). Makefile.am has a couple of special rules that generate .cc files from .re and .y files. In this case we'll probably need a rule that autogenerates manpage from .h files (and .rst files on gh-pages-gen branch).

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 bootstrap subdirectory, so that one can build re2c with minimum dependencies on any system.

As for my contributions, I only wanted to study and fix the docs. I don't plan on contributing much beyond this.

You are welcome in any case. :)

@pskocik

This comment has been minimized.

Copy link
Contributor Author

commented Apr 9, 2017

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
to now pull the manual directory from master and regenerate the pngs.

I think it is simple and deduplicates the documentation well.

The build system on master could additionally use something like:

#include  <stdio.h>
#include  <unistd.h>

int main(void)
{
    FILE *f = popen(
    "MANWIDTH=88 PAGER=cat man re2c 2>/dev/null| sed -n '/^OPTIONS/,/^INTERFACE/ { s/^       //; /^[ -]/ p;}'"
    , 
    "r");
    if(!f) { perror("popen");  exit(1); }

    int  ch; 
    puts("namespace re2c { extern char const help_string [] = { ");
    while (EOF != (ch=fgetc(f)))
        printf("'\\x%x',\n", ch);
    puts("}; }");
    return (!ferror(f) && 0==pclose(f) && !ferror(stdout)) ? EXIT_SUCCESS : EXIT_FAILURE;

}

to generate a help_string.cc out of the newly built manpage. The file would define char const re2c::help_string[]; and usage() could simply echo this string (generating this on the fly would make the --help flag laggy as the man command takes about 200ms).

@skvadrik

This comment has been minimized.

Copy link
Owner

commented Apr 9, 2017

The first part (syncing online docs with manpage) looks good, except for the following:

  • don't move the whole manual directory, move only those files that are included in doc/manpage.rst.in on master
  • don't regenerate pictures (it is hard to check if they still look as intended on every build)

If we agree on these two issues, I would gladly accept this part.

Now for the second part (syncing help with manpage).
I still think that it's better to generate .rst from source files, except for the disadvantage that C-strings lack markup (highlighting keywords, etc.). But no matter which direction we choose, the way to add synchronization is as follows:

  • create a synchronization utility (the C++ program you suggested is fine, but a simple shell scrpt would be better)
  • create bootstrap versions of the autogenerated files and put them in bootstrap/... subdir: these files would be used by build system, unless
  • re2c was configured with option --enable-docs: currently this option makes the build system regenerate manpage using rst2man, we would need one more step to regenarate help from .rst or .rst from help.

If you don't feel like digging in Makefile.am, I can do this.

@pskocik

This comment has been minimized.

Copy link
Contributor Author

commented Apr 9, 2017

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.

#include  <stdio.h>

int main(int c, char **v)
{
    if(0>setenv( "RE2C_MANPAGE", c>1 ? v[1] : "re2c",  1))
        { perror("setenv"); return EXIT_FAILURE; }

    FILE *f = popen(
    "MANWIDTH=88 PAGER=cat man \"$RE2C_MANPAGE\" 2>/dev/null| sed -n '/^OPTIONS/,/^INTERFACE/ { s/^       //; /^[ -]/ p;}'"
    , 
    "r");
    if(!f) { perror("popen");  exit(1); }

    int  ch; 
    puts("namespace re2c { extern char const help_string [] = { ");
    while (EOF != (ch=fgetc(f)))
        printf("'\\x%x',\n", ch);
    puts("}; }");
    return (!ferror(f) && 0==pclose(f) && !ferror(stdout)) ? EXIT_SUCCESS : EXIT_FAILURE;

}

@skvadrik

This comment has been minimized.

Copy link
Owner

commented Apr 10, 2017

Part 2: f9a34ba, not the best way it but at least make distcheck seems to work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.