Re: [PATCH 2/3] Add generated .opt.urls files
Marc Poulhiès writes: >> Perhaps this script could also deal directly with Sphinx-generated >> HTML? > > I investigated a bit... The Ada part doesn't handle the html target, so > it's expected you don't have anything to parse. The online docs are > generated using a different script, not using these makefiles. > > I'll see if I can fix the html target for ada, so that your script > doesn't need to be changed :) > >>> We are generating the texinfo files >>> from sphinx, so maybe we could adjust the script to also match what >>> the >>> sphinx generator produces? >> >> It *might* be as simple as pointing it at the option index for the >> generated HTML for Ada. > > That's worth a try, when/if I can fix the HTML target. FYI, I've committed a simple patch for having the HTML documentation correctly generated when invoking "make html" (r14-6712) so maybe you can also enable it for the Ada frontend. But that will probably not produce any useful output as most compiler options for GNAT are handled in the frontend (no .opt and the actual messages are emitted without using gcc's mechanism). Marc
Re: [PATCH 2/3] Add generated .opt.urls files
David Malcolm writes: > > The new regenerate-opt-urls.py script only parsed > buildir/gcc/HTML/gcc-14.0.0/gcc/Option-Index.html > looking for anchors for options via a regex. > > Looking at my build, I don't see any generated Ada HTML docs, so maybe > I messed this up? Does the generated HTML from the generated Ada > texinfo go somewhere else? (and, in particular, does it have its own > index?) > > Perhaps this script could also deal directly with Sphinx-generated > HTML? I investigated a bit... The Ada part doesn't handle the html target, so it's expected you don't have anything to parse. The online docs are generated using a different script, not using these makefiles. I'll see if I can fix the html target for ada, so that your script doesn't need to be changed :) >> We are generating the texinfo files >> from sphinx, so maybe we could adjust the script to also match what >> the >> sphinx generator produces? > > It *might* be as simple as pointing it at the option index for the > generated HTML for Ada. That's worth a try, when/if I can fix the HTML target. Marc
Re: [PATCH 2/3] Add generated .opt.urls files
On Sun, 2023-11-12 at 11:56 +0100, Iain Buclaw wrote: > Excerpts from David Malcolm's message of November 10, 2023 10:42 pm: > > gcc/d/ChangeLog: > > * lang.opt.urls: New file, autogenerated by > > regenerate-opt-urls.py. > > --- > > gcc/d/lang.opt.urls | 95 + > > create mode 100644 gcc/d/lang.opt.urls > > > > [abridged view of patch] > > > diff --git a/gcc/d/lang.opt.urls b/gcc/d/lang.opt.urls > > new file mode 100644 > > index ..57c14ecc459a > > --- /dev/null > > +++ b/gcc/d/lang.opt.urls > > @@ -0,0 +1,95 @@ > > +; Autogenerated by regenerate-opt-urls.py from gcc/d/lang.opt and > > generated HTML > > + > > +H > > +UrlSuffix(gcc/Preprocessor-Options.html#index-H) > > + > > +I > > +UrlSuffix(gcc/Directory-Options.html#index-I) > > + > > +M > > +UrlSuffix(gcc/Preprocessor-Options.html#index-M) > > + > > +MD > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MD) > > + > > +MF > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MF) > > + > > +MG > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MG) > > + > > +MM > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MM) > > + > > +MMD > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MMD) > > + > > +MP > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MP) > > + > > +MT > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MT) > > + > > +MQ > > +UrlSuffix(gcc/Preprocessor-Options.html#index-MQ) > > + > > +Waddress > > +UrlSuffix(gcc/Warning-Options.html#index-Waddress) > > + > > +; skipping 'Wall' due to multiple URLs: > > +; duplicate: 'gcc/Standard-Libraries.html#index-Wall-1' > > +; duplicate: 'gcc/Warning-Options.html#index-Wall' > > + > > +Walloca > > +UrlSuffix(gcc/Warning-Options.html#index-Walloca) > > + > > +Walloca-larger-than= > > +UrlSuffix(gcc/Warning-Options.html#index-Walloca-larger-than_003d) > > + > > +Wbuiltin-declaration-mismatch > > +UrlSuffix(gcc/Warning-Options.html#index-Wbuiltin-declaration- > > mismatch) > > + > > +Wdeprecated > > +UrlSuffix(gcc/Warning-Options.html#index-Wdeprecated) > > + > > +Werror > > +UrlSuffix(gcc/Warning-Options.html#index-Werror) > > + > > +Wextra > > +UrlSuffix(gcc/Warning-Options.html#index-Wextra) > > + > > +Wunknown-pragmas > > +UrlSuffix(gcc/Warning-Options.html#index-Wno-unknown-pragmas) > > + > > +Wvarargs > > +UrlSuffix(gcc/Warning-Options.html#index-Wno-varargs) > > + > > +; skipping 'fbuiltin' due to multiple URLs: > > +; duplicate: 'gcc/C-Dialect-Options.html#index-fbuiltin' > > +; duplicate: 'gcc/Other-Builtins.html#index-fno-builtin-3' > > +; duplicate: 'gcc/Warning-Options.html#index-fno-builtin-1' > > + > > +fexceptions > > +UrlSuffix(gcc/Code-Gen-Options.html#index-fexceptions) > > + > > +frtti > > +UrlSuffix(gcc/C_002b_002b-Dialect-Options.html#index-fno-rtti) > > + > > +imultilib > > +UrlSuffix(gcc/Directory-Options.html#index-imultilib) > > + > > +iprefix > > +UrlSuffix(gcc/Directory-Options.html#index-iprefix) > > + > > +isysroot > > +UrlSuffix(gcc/Directory-Options.html#index-isysroot) > > + > > +isystem > > +UrlSuffix(gcc/Directory-Options.html#index-isystem) > > + > > +nostdinc > > +UrlSuffix(gcc/Directory-Options.html#index-nostdinc) > > + > > +v > > +UrlSuffix(gcc/Overall-Options.html#index-v) > > + > > -- > > 2.26.3 > > > > > > So I see this focuses on only adding URLs for common options, or > options > that relate to C/C++ family, but may be handled by other front-ends > too? The regenerate-opt-urls.py script only parsed buildir/gcc/HTML/gcc-14.0.0/gcc/Option-Index.html looking for anchors for options via a regex. Looking at the docs I now see that various frontends have their own Option-Index.html, e.g.: gdc/Option-Index.html so probably regenerate-opt-urls.py ought to be parsing those also, and marking the generated .opt.urls as being lang-specific. That way we could (somehow) generate a options-urls.cc that has logic (perhaps with langmasks) for giving out different URLs for different frontends. > > To pick out one, you have: > > frtti > UrlSuffix(gcc/C_002b_002b-Dialect-Options.html#index-fno-rtti) > > It looks like it could could alternatively be > > frtti > UrlSuffix(gdc/Runtime-Options.html#index-frtti) > > Or are other front-ends having URLs to their language-specific > documentation pages not supported for the same reason as why they > can't > add self-documentation to their own options if another front-end > (typically C/C++) also makes claim to the option? Implementation-wise that would need fixing in the way I'm handling the UrlSuffix directives; perhaps with a LangUrlSuffix directive. > > frtti > D > ; Documented in C > > > I'm OK with the D parts regardless of this observation. Thanks Dave
Re: [PATCH 2/3] Add generated .opt.urls files
On Mon, 2023-11-13 at 14:11 +0100, Marc Poulhiès wrote: > > David Malcolm writes: > > > gcc/ada/ChangeLog: > > * gcc-interface/lang.opt.urls: New file, autogenerated by > > regenerate-opt-urls.py. > > > > diff --git a/gcc/ada/gcc-interface/lang.opt.urls b/gcc/ada/gcc- > > interface/lang.opt.urls > > new file mode 100644 > > index ..e24210bcb12a > > --- /dev/null > > +++ b/gcc/ada/gcc-interface/lang.opt.urls > > @@ -0,0 +1,28 @@ > > +; Autogenerated by regenerate-opt-urls.py from gcc/ada/gcc- > > interface/lang.opt and generated HTML > > + > > +I > > +UrlSuffix(gcc/Directory-Options.html#index-I) > > + > > +; skipping 'Wall' due to multiple URLs: > > +; duplicate: 'gcc/Standard-Libraries.html#index-Wall-1' > > +; duplicate: 'gcc/Warning-Options.html#index-Wall' > > + > > +nostdinc > > +UrlSuffix(gcc/Directory-Options.html#index-nostdinc) > > + > > +nostdlib > > +UrlSuffix(gcc/Link-Options.html#index-nostdlib) > > + > > +; skipping 'fshort-enums' due to multiple URLs: > > +; duplicate: 'gcc/Code-Gen-Options.html#index-fshort-enums' > > +; duplicate: 'gcc/Non-bugs.html#index-fshort-enums-3' > > +; duplicate: 'gcc/Structures-unions-enumerations-and-bit-fields- > > implementation.html#index-fshort-enums-1' > > + > > +; skipping 'fsigned-char' due to multiple URLs: > > +; duplicate: 'gcc/C-Dialect-Options.html#index-fsigned-char' > > +; duplicate: 'gcc/Characters-implementation.html#index-fsigned- > > char-1' > > + > > +; skipping 'funsigned-char' due to multiple URLs: > > +; duplicate: 'gcc/C-Dialect-Options.html#index-funsigned-char' > > +; duplicate: 'gcc/Characters-implementation.html#index- > > funsigned-char-1' > > Hello David, > > This looks very nice, thanks! > > I wonder why the Ada frontend only gets I, nostdinc and nostdlib > URLified to the common gcc doc. > > Is it possible that your doc scrapper doesn't match the option in the > Ada doc? We are documenting nostdlib, nostdinc and I, so I would also > expect a "multiple URLs" for these. The new regenerate-opt-urls.py script only parsed buildir/gcc/HTML/gcc-14.0.0/gcc/Option-Index.html looking for anchors for options via a regex. Looking at my build, I don't see any generated Ada HTML docs, so maybe I messed this up? Does the generated HTML from the generated Ada texinfo go somewhere else? (and, in particular, does it have its own index?) Perhaps this script could also deal directly with Sphinx-generated HTML? > We are generating the texinfo files > from sphinx, so maybe we could adjust the script to also match what > the > sphinx generator produces? It *might* be as simple as pointing it at the option index for the generated HTML for Ada. Though as Iain's email points out, there may be some issues with per- language URLs for options that my approach doesn't quite handle yet. Dave
Re: [PATCH 2/3] Add generated .opt.urls files
David Malcolm writes: > gcc/ada/ChangeLog: > * gcc-interface/lang.opt.urls: New file, autogenerated by > regenerate-opt-urls.py. > diff --git a/gcc/ada/gcc-interface/lang.opt.urls > b/gcc/ada/gcc-interface/lang.opt.urls > new file mode 100644 > index ..e24210bcb12a > --- /dev/null > +++ b/gcc/ada/gcc-interface/lang.opt.urls > @@ -0,0 +1,28 @@ > +; Autogenerated by regenerate-opt-urls.py from > gcc/ada/gcc-interface/lang.opt and generated HTML > + > +I > +UrlSuffix(gcc/Directory-Options.html#index-I) > + > +; skipping 'Wall' due to multiple URLs: > +; duplicate: 'gcc/Standard-Libraries.html#index-Wall-1' > +; duplicate: 'gcc/Warning-Options.html#index-Wall' > + > +nostdinc > +UrlSuffix(gcc/Directory-Options.html#index-nostdinc) > + > +nostdlib > +UrlSuffix(gcc/Link-Options.html#index-nostdlib) > + > +; skipping 'fshort-enums' due to multiple URLs: > +; duplicate: 'gcc/Code-Gen-Options.html#index-fshort-enums' > +; duplicate: 'gcc/Non-bugs.html#index-fshort-enums-3' > +; duplicate: > 'gcc/Structures-unions-enumerations-and-bit-fields-implementation.html#index-fshort-enums-1' > + > +; skipping 'fsigned-char' due to multiple URLs: > +; duplicate: 'gcc/C-Dialect-Options.html#index-fsigned-char' > +; duplicate: 'gcc/Characters-implementation.html#index-fsigned-char-1' > + > +; skipping 'funsigned-char' due to multiple URLs: > +; duplicate: 'gcc/C-Dialect-Options.html#index-funsigned-char' > +; duplicate: 'gcc/Characters-implementation.html#index-funsigned-char-1' Hello David, This looks very nice, thanks! I wonder why the Ada frontend only gets I, nostdinc and nostdlib URLified to the common gcc doc. Is it possible that your doc scrapper doesn't match the option in the Ada doc? We are documenting nostdlib, nostdinc and I, so I would also expect a "multiple URLs" for these. We are generating the texinfo files from sphinx, so maybe we could adjust the script to also match what the sphinx generator produces? Thanks, Marc
Re: [PATCH 2/3] Add generated .opt.urls files
Excerpts from David Malcolm's message of November 10, 2023 10:42 pm: > gcc/d/ChangeLog: > * lang.opt.urls: New file, autogenerated by > regenerate-opt-urls.py. > --- > gcc/d/lang.opt.urls | 95 + > create mode 100644 gcc/d/lang.opt.urls > [abridged view of patch] > diff --git a/gcc/d/lang.opt.urls b/gcc/d/lang.opt.urls > new file mode 100644 > index ..57c14ecc459a > --- /dev/null > +++ b/gcc/d/lang.opt.urls > @@ -0,0 +1,95 @@ > +; Autogenerated by regenerate-opt-urls.py from gcc/d/lang.opt and generated > HTML > + > +H > +UrlSuffix(gcc/Preprocessor-Options.html#index-H) > + > +I > +UrlSuffix(gcc/Directory-Options.html#index-I) > + > +M > +UrlSuffix(gcc/Preprocessor-Options.html#index-M) > + > +MD > +UrlSuffix(gcc/Preprocessor-Options.html#index-MD) > + > +MF > +UrlSuffix(gcc/Preprocessor-Options.html#index-MF) > + > +MG > +UrlSuffix(gcc/Preprocessor-Options.html#index-MG) > + > +MM > +UrlSuffix(gcc/Preprocessor-Options.html#index-MM) > + > +MMD > +UrlSuffix(gcc/Preprocessor-Options.html#index-MMD) > + > +MP > +UrlSuffix(gcc/Preprocessor-Options.html#index-MP) > + > +MT > +UrlSuffix(gcc/Preprocessor-Options.html#index-MT) > + > +MQ > +UrlSuffix(gcc/Preprocessor-Options.html#index-MQ) > + > +Waddress > +UrlSuffix(gcc/Warning-Options.html#index-Waddress) > + > +; skipping 'Wall' due to multiple URLs: > +; duplicate: 'gcc/Standard-Libraries.html#index-Wall-1' > +; duplicate: 'gcc/Warning-Options.html#index-Wall' > + > +Walloca > +UrlSuffix(gcc/Warning-Options.html#index-Walloca) > + > +Walloca-larger-than= > +UrlSuffix(gcc/Warning-Options.html#index-Walloca-larger-than_003d) > + > +Wbuiltin-declaration-mismatch > +UrlSuffix(gcc/Warning-Options.html#index-Wbuiltin-declaration-mismatch) > + > +Wdeprecated > +UrlSuffix(gcc/Warning-Options.html#index-Wdeprecated) > + > +Werror > +UrlSuffix(gcc/Warning-Options.html#index-Werror) > + > +Wextra > +UrlSuffix(gcc/Warning-Options.html#index-Wextra) > + > +Wunknown-pragmas > +UrlSuffix(gcc/Warning-Options.html#index-Wno-unknown-pragmas) > + > +Wvarargs > +UrlSuffix(gcc/Warning-Options.html#index-Wno-varargs) > + > +; skipping 'fbuiltin' due to multiple URLs: > +; duplicate: 'gcc/C-Dialect-Options.html#index-fbuiltin' > +; duplicate: 'gcc/Other-Builtins.html#index-fno-builtin-3' > +; duplicate: 'gcc/Warning-Options.html#index-fno-builtin-1' > + > +fexceptions > +UrlSuffix(gcc/Code-Gen-Options.html#index-fexceptions) > + > +frtti > +UrlSuffix(gcc/C_002b_002b-Dialect-Options.html#index-fno-rtti) > + > +imultilib > +UrlSuffix(gcc/Directory-Options.html#index-imultilib) > + > +iprefix > +UrlSuffix(gcc/Directory-Options.html#index-iprefix) > + > +isysroot > +UrlSuffix(gcc/Directory-Options.html#index-isysroot) > + > +isystem > +UrlSuffix(gcc/Directory-Options.html#index-isystem) > + > +nostdinc > +UrlSuffix(gcc/Directory-Options.html#index-nostdinc) > + > +v > +UrlSuffix(gcc/Overall-Options.html#index-v) > + > -- > 2.26.3 > > So I see this focuses on only adding URLs for common options, or options that relate to C/C++ family, but may be handled by other front-ends too? To pick out one, you have: frtti UrlSuffix(gcc/C_002b_002b-Dialect-Options.html#index-fno-rtti) It looks like it could could alternatively be frtti UrlSuffix(gdc/Runtime-Options.html#index-frtti) Or are other front-ends having URLs to their language-specific documentation pages not supported for the same reason as why they can't add self-documentation to their own options if another front-end (typically C/C++) also makes claim to the option? frtti D ; Documented in C I'm OK with the D parts regardless of this observation. Thanks, Iain.
