| Message ID | 20161123063807.14845-2-ricaljasan@pacific.net |
|---|---|
| State | New |
| Headers | show |
On Tue, 22 Nov 2016, Rical Jasan wrote: > Multiple headers may be defined as long as they are all on the > second-to-last line, and not separated by commas. Standards > are rendered free-form, so there is no need to refactor them > as long as they are present. > > Deviating from summary.awk, the header and standards > annotations must occur on the two lines immediately preceding > the item to be annotated (this simplifies future work and > doesn't change summary.awk's output). Additionally, @comments > immediately preceding header and standards @comments are > disallowed (note that @c-comments are still valid). The > latter requirement may not be essential once all annotations > are otherwise conforming, but it was useful as a heuristic for > finding ill-formatted annotations in the meantime, enforcing a > stricter syntax that is still summary.awk-compatible. I think you should expand the comment in summary.awk that describes the syntax to detail these more precise rules, and to say explicitly how to indicate multiple headers or standards (or cases where the headers depend on the standard?). (Ideally of course summary.awk or some other script run during the build would exit with error status if the more precise rules aren't met, to ensure that new deviations don't creep in.) -- Joseph S. Myers joseph@codesourcery.com
On 11/23/2016 09:30 AM, Joseph Myers wrote: > On Tue, 22 Nov 2016, Rical Jasan wrote: > >> Multiple headers may be defined as long as they are all on the >> second-to-last line, and not separated by commas. Standards >> are rendered free-form, so there is no need to refactor them >> as long as they are present. >> >> Deviating from summary.awk, the header and standards >> annotations must occur on the two lines immediately preceding >> the item to be annotated (this simplifies future work and >> doesn't change summary.awk's output). Additionally, @comments >> immediately preceding header and standards @comments are >> disallowed (note that @c-comments are still valid). The >> latter requirement may not be essential once all annotations >> are otherwise conforming, but it was useful as a heuristic for >> finding ill-formatted annotations in the meantime, enforcing a >> stricter syntax that is still summary.awk-compatible. > > I think you should expand the comment in summary.awk that describes the > syntax to detail these more precise rules, and to say explicitly how to > indicate multiple headers or standards (or cases where the headers depend > on the standard?). (Ideally of course summary.awk or some other script > run during the build would exit with error status if the more precise > rules aren't met, to ensure that new deviations don't creep in.) This was going to be the topic of my question to the list, so I'm glad you brought this up. I realize it would be ideal to provide a script (or rework summary.awk) to enforce syntax along with the changes, but I withheld that work for several reasons. First, I was going to ask if there was a preference for whether summary.awk should be modified or if a new script was acceptable, and if so which language. To help make sense of things while working this out I used a Perl script for a scratchpad, which I could clean up for submission. I could also write it in AWK. If a new script was used for syntax-checking, would you prefer it to take over the generation of summary.texi? The two functions are intrinsically related. Second, I expect we'll move away from @comment-based annotations to something more explicit/obvious, so I was avoiding enforcing a syntax until we settle on one. (Not that it's an argument against enforcing now.) For example, I'm already using new @vitem and @titem macros to handle a couple corner cases (which a syntax-checker at this stage wouldn't catch anyway), and am leaning towards empty macros to replace the header and standards @comments. There is also the issue of what standards annotations will eventually look like (for which I'm grateful for your comments on the other patch). Third, the changes in this patchset merely take advantage of summary.awk's behaviour. The result is a more complete manual, operating under the exact same paradigm it was before. My idea was that it improves the manual in its current state, so that if (worst case) nothing else were to happen with this, that's OK, and things are better. Having nearly complete annotations, even using the current, unenforced syntax, will also make future work on a real framework for headers and standards easier, resulting in a strategic win-win. Ultimately, though, I just really wanted to get the bulk of the new material submitted sooner rather than later. :) This patchset introduces a lot of new material to be reviewed (all new content being in 3/3). If you'd rather wait until there's a more comprehensive proposal, I don't mind doing it that way either. Rical
On Thu, 24 Nov 2016, Rical Jasan wrote: > First, I was going to ask if there was a preference for whether > summary.awk should be modified or if a new script was acceptable, and if > so which language. To help make sense of things while working this out > I used a Perl script for a scratchpad, which I could clean up for Building the manual already requires perl (to generate libm-err.texi) so use of perl is not necessarily a problem. > Second, I expect we'll move away from @comment-based annotations to > something more explicit/obvious, so I was avoiding enforcing a syntax > until we settle on one. (Not that it's an argument against enforcing > now.) For example, I'm already using new @vitem and @titem macros to My view is that when patches cause the manual to meet particular syntax rules that help conversion to another form of annotations, they should also make sure those rules are enforced so we don't regress before the conversion. -- Joseph S. Myers joseph@codesourcery.com
On 11/24/2016 05:17 AM, Joseph Myers wrote: > On Thu, 24 Nov 2016, Rical Jasan wrote: > >> First, I was going to ask if there was a preference for whether >> summary.awk should be modified or if a new script was acceptable, and if >> so which language. To help make sense of things while working this out >> I used a Perl script for a scratchpad, which I could clean up for > > Building the manual already requires perl (to generate libm-err.texi) so > use of perl is not necessarily a problem. > >> Second, I expect we'll move away from @comment-based annotations to >> something more explicit/obvious, so I was avoiding enforcing a syntax >> until we settle on one. (Not that it's an argument against enforcing >> now.) For example, I'm already using new @vitem and @titem macros to > > My view is that when patches cause the manual to meet particular syntax > rules that help conversion to another form of annotations, they should > also make sure those rules are enforced so we don't regress before the > conversion. I'll whittle down what I've been using to the bare essentials and submit it with a v2 then. Practically, changing the @comments to something else should only result in modifying a couple regexes anyway. What should I do with summary.awk? Replace it or stick to syntax checking only? I've been calling mine check-stds.pl but it could become summary.pl. I suppose replacing summary.awk could always be done later, too. Rical
On Fri, 25 Nov 2016, Rical Jasan wrote: > What should I do with summary.awk? Replace it or stick to syntax > checking only? I've been calling mine check-stds.pl but it could become I'm not making a particular assertion about whether the scripts should be combined or not (provided that any replacement for summary.awk generates identical output, given any required fixes to the manual sources). -- Joseph S. Myers joseph@codesourcery.com
On 11/25/2016 06:25 AM, Joseph Myers wrote: > On Fri, 25 Nov 2016, Rical Jasan wrote: > >> What should I do with summary.awk? Replace it or stick to syntax >> checking only? I've been calling mine check-stds.pl but it could become > > I'm not making a particular assertion about whether the scripts should be > combined or not (provided that any replacement for summary.awk generates > identical output, given any required fixes to the manual sources). Just an update, I've pared down the script I had to something suitable for a purely automated syntax-checker, and I'll include it with a v2 along with the other issues mentioned. I won't touch summary.awk because once we change the entire standards annotation framework, both summary.awk and the new script will need to be rewritten anyway, so I think it would be better to pursue a combined script at that stage. Rical
diff --git a/manual/filesys.texi b/manual/filesys.texi index 26758e6..dc047c0 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -3559,9 +3559,9 @@ opening the file you should use the @code{O_EXCL} flag. Using @end deftypefun @cindex TMPDIR environment variable +@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not?? @comment stdio.h @comment SVID -@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not?? @deftypevr {SVID Macro} {char *} P_tmpdir This macro is the name of the default directory for temporary files. @end deftypevr diff --git a/manual/lang.texi b/manual/lang.texi index 6281840..b6ad703 100644 --- a/manual/lang.texi +++ b/manual/lang.texi @@ -1114,7 +1114,7 @@ This is the number of base-@code{FLT_RADIX} digits in the floating point mantissa for the data types @code{double} and @code{long double}, respectively. -@comment Extra blank lines make it look better. +@c Extra blank lines make it look better. @comment float.h @comment ISO @item FLT_DIG diff --git a/manual/locale.texi b/manual/locale.texi index 780ce01..ae71ccc 100644 --- a/manual/locale.texi +++ b/manual/locale.texi @@ -1406,8 +1406,8 @@ English. @Theglibc{} contains @code{rpmatch} to give applications easy access to the corresponding locale definitions. -@comment GNU @comment stdlib.h +@comment GNU @deftypefun int rpmatch (const char *@var{response}) @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Calls nl_langinfo with YESEXPR and NOEXPR, triggering @mtslocale but diff --git a/manual/time.texi b/manual/time.texi index 6a899b7..e590c77 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -2740,9 +2740,9 @@ by @var{which} in the structure pointed at by @var{old}. The return value and error conditions are the same as for @code{setitimer}. @end deftypefun +@vtable @code @comment sys/time.h @comment BSD -@vtable @code @item ITIMER_REAL This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the real-time diff --git a/manual/users.texi b/manual/users.texi index 0d94db1..0924f39 100644 --- a/manual/users.texi +++ b/manual/users.texi @@ -1674,8 +1674,7 @@ You can translate between a traditional @code{struct utmp} and an XPG these functions are merely copies, since the two structures are identical. -@comment utmpx.h -@comment utmp.h +@comment utmp.h utmpx.h @comment GNU @deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @@ -1683,8 +1682,7 @@ identical. compatible, from @var{utmpx} to @var{utmp}. @end deftypefun -@comment utmpx.h -@comment utmp.h +@comment utmp.h utmpx.h @comment GNU @deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}