strftime man page is garbled

strftime man page is garbled

[Wayne Pollock]

The description section of the strftime man page is
garbled.  The first paragraph shows as this:

=============================

       into a null-terminated string, starting at S and occupying no more than
MAXSIZE characters.

          You  control the format of the output using the string at FORMAT.
literally into the formatted string, and
       time conversion specifications.  Time conversion specifications are two- and
three-character sequences  begin‐
       ning  with  ''%'' (use ''%%'' to include a percent sign in the output).  Each
defined conversion specification
       selects only the specified field(s) of calendar time data from '*TIMP', and
converts it to a string in one  of
       the following ways:

============================

In addition, none of the option letters show, only the
option descriptions.  The info node at
"info libc timefns strftime" appears to be fine.

I have cygwin-doc version 1.7.35-1.
(I have a locale of C.UTF-8, if it matters.)

-- 
Wayne Pollock

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: strftime man page is garbled

[Marco Atzeri]

[-- Attachment #1: Type: text/plain, Size: 1220 bytes --]



On 6/4/2015 3:18 AM, Wayne Pollock wrote:
> The description section of the strftime man page is
> garbled.  The first paragraph shows as this:
>
> =============================
>
>         into a null-terminated string, starting at S and occupying no more than
> MAXSIZE characters.
>
>            You  control the format of the output using the string at FORMAT.
> literally into the formatted string, and
>         time conversion specifications.  Time conversion specifications are two- and
> three-character sequences  begin‐
>         ning  with  ''%'' (use ''%%'' to include a percent sign in the output).  Each
> defined conversion specification
>         selects only the specified field(s) of calendar time data from '*TIMP', and
> converts it to a string in one  of
>         the following ways:
>
> ============================
>
> In addition, none of the option letters show, only the
> option descriptions.  The info node at
> "info libc timefns strftime" appears to be fine.
>
> I have cygwin-doc version 1.7.35-1.
> (I have a locale of C.UTF-8, if it matters.)
>

Works fine for me, I have a complete man page
see attached.

looks at the output of
   man -d strftime

for any hint.

Regards
Marco

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: man-strftime.txt --]
[-- Type: text/plain; charset=windows-1252; name="man-strftime.txt", Size: 9940 bytes --]

STRFTIME(3)                         NEWLIB                         STRFTIME(3)



NAME
       9.8 'strftime'--convert date and time to a formatted string


SYNOPSIS
            #include <time.h>
            size_t strftime(char *restrict S, size_t MAXSIZE,
                const char *restrict FORMAT,
                const struct tm *restrict TIMP);


DESCRIPTION
       into a null-terminated string, starting at S and occupying no more than
       MAXSIZE characters.

          You control the format of the output using  the  string  at  FORMAT.
       literally  into  the  formatted  string, and time conversion specifica‐
       tions.  Time conversion specifications  are  two-  and  three-character
       sequences beginning with ''%'' (use ''%%'' to include a percent sign in
       the output).  Each defined conversion specification  selects  only  the
       specified  field(s) of calendar time data from '*TIMP', and converts it
       to a string in one of the following ways:

            The abbreviated weekday name according to the current locale.
            [tm_wday]

            The full weekday name according to the current locale.  In the
            default "C" locale, one of ''Sunday'', ''Monday'', ''Tuesday'',
            ''Wednesday'', ''Thursday'', ''Friday'', ''Saturday''.  [tm_wday]

            The abbreviated month name according to the current locale.
            [tm_mon]

            The full month name according to the current locale.  In the
            default "C" locale, one of ''January'', ''February'', ''March'',
            ''April'', ''May'', ''June'', ''July'', ''August'', ''September'',
            ''October'', ''November'', ''December''.  [tm_mon]

            The preferred date and time representation for the current locale.
            [tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday]

            The century, that is, the year divided by 100 then truncated.  For
            4-digit years, the result is zero-padded and exactly two
            characters; but for other years, there may a negative sign or more
            digits.  In this way, ''%C%y'' is equivalent to ''%Y''.  [tm_year]
            The day of the month, formatted with two digits (from ''01'' to
            ''31'').  [tm_mday]

            A string representing the date, in the form ''"%m/%d/%y"''.
            [tm_mday, tm_mon, tm_year]

            The day of the month, formatted with leading space if single digit
            (from ''1'' to ''31'').  [tm_mday]

            In some locales, the E modifier  selects  alternative  representa‐
       tions
            of  certain  modifiers 'x'.  In newlib, it is ignored, and treated
       as
            %'x'.

            A string representing the ISO 8601:2000 date format, in the form
            ''"%Y-%m-%d"''.  [tm_mday, tm_mon, tm_year]

            The last two digits of the week-based year, see specifier %G (from
            ''00'' to ''99'').  [tm_year, tm_wday, tm_yday]

            The week-based year.  In the ISO 8601:2000 calendar, week 1 of the
            year includes January 4th, and begin on Mondays.  Therefore, if
            January 1st, 2nd, or 3rd falls on a Sunday, that day and earlier
            belong to the last week of the  previous  year;  and  if  December
       29th,
            30th, or 31st falls on Monday, that day and later belong to week 1
            of the next year.  For consistency with %Y, it always has at least
            four  characters.   Example:  "%G"  for  Saturday 2nd January 1999
       gives
            "1998",  and  for  Tuesday  30th  December  1997   gives   "1998".
       [tm_year,
            tm_wday, tm_yday]

            Synonym for "%b".  [tm_mon]

            The hour (on a 24-hour clock), formatted with two digits (from
            ''00'' to ''23'').  [tm_hour]

            The hour (on a 12-hour clock), formatted with two digits (from
            ''01'' to ''12'').  [tm_hour]

            The count of days in the year, formatted with three digits (from
            ''001'' to ''366'').  [tm_yday]

            The hour (on a 24-hour clock), formatted with leading space if
            single digit (from ''0'' to ''23'').  Non-POSIX extension (c.p.
            %I). [tm_hour]

            The hour (on a 12-hour clock), formatted with leading space if
            single digit (from ''1'' to ''12'').  Non-POSIX extension (c.p.
            %H). [tm_hour]

            The month number, formatted with two digits (from ''01'' to
            ''12'').  [tm_mon]

            The minute, formatted with two digits (from ''00'' to ''59'').
            [tm_min]

            A newline character (''0').

            In some locales, the O modifier selects alternative digit
            characters for certain modifiers 'x'.  In newlib, it is ignored,
            and treated as %'x'.

            Either ''AM'' or ''PM'' as appropriate, or the corresponding
            strings for the current locale.  [tm_hour]

            Same as ''%p'', but in lowercase.  This is a GNU extension.
            [tm_hour]

            Replaced by the time in a.m.  and p.m.  notation.  In the "C"
            locale  this  is  equivalent  to  "%I:%M:%S %p".  In locales which
       don't
            define a.m./p.m.  notations, the result is an empty string.
            [tm_sec, tm_min, tm_hour]

            The 24-hour time, to the minute.  Equivalent to "%H:%M". [tm_min,
            tm_hour]

            The second, formatted with two digits  (from  ''00''  to  ''60'').
       The
            value 60 accounts for the occasional leap second.  [tm_sec]

            A tab character ('''').

            The 24-hour time, to the second.  Equivalent to "%H:%M:%S".
            [tm_sec, tm_min, tm_hour]

            The  weekday  as  a  number,  1-based  from  Monday (from ''1'' to
       ''7'').
            [tm_wday]

            The week number, where weeks start on Sunday, week 1 contains the
            first Sunday in a year, and earlier days are in week 0.  Formatted
            with  two  digits  (from  ''00''  to  ''53'').   See  also   '%W'.
       [tm_wday,
            tm_yday]

            The week number, where weeks start on Monday, week 1 contains
            January 4th, and earlier days are in the previous year.  Formatted
            with   two  digits  (from  ''01''  to  ''53'').   See  also  '%G'.
       [tm_year,
            tm_wday, tm_yday]

            The weekday as a  number,  0-based  from  Sunday  (from  ''0''  to
       ''6'').
            [tm_wday]

            The week number, where weeks start on Monday, week 1 contains the
            first Monday in a year, and earlier days are in week 0.  Formatted
            with two digits (from ''00'' to ''53'').  [tm_wday, tm_yday]

            Replaced by the preferred date representation in the current
            locale.  In the "C" locale this is equivalent to "%m/%d/%y".
            [tm_mon, tm_mday, tm_year]

            Replaced by the preferred time representation in the current
            locale.  In the "C" locale this is equivalent to "%H:%M:%S".
            [tm_sec, tm_min, tm_hour]

            The  last  two  digits  of  the  year  (from  ''00''  to  ''99'').
       [tm_year]
            (Implementation interpretation: always positive, even for negative
            years.)

            The full year, equivalent to '%C%y'.  It will always have at least
            four characters, but may have more.  The  year  is  accurate  even
       when
            tm_year added to the offset of 1900 overflows an int.  [tm_year]

            The offset from UTC. The format consists of a sign (negative is
            west  of  Greewich),  two characters for hour, then two characters
       for
            minutes (-hhmm or +hhmm).  If tm_isdst is negative, the offset is
            unknown and no output is generated; if it is zero, the offset is
            the standard offset for the current time zone; and if it is
            positive, the offset is the daylight savings offset for  the  cur‐
       rent
            timezone.  The offset is determined from the TZ environment
            variable, as if by calling tzset().  [tm_isdst]

            The time zone name.  If tm_isdst is negative, no output is
            generated.  Otherwise, the time zone name is based on the TZ
            environment variable, as if by calling tzset().  [tm_isdst]

            A single character, ''%''.



RETURNS
       When  the  formatted time takes up no more than MAXSIZE characters, the
       result is the length of the formatted string.  Otherwise, if  the  for‐
       matting operation was abandoned due to lack of room, the result is



PORTABILITY
       ANSI  C  requires 'strftime', but does not specify the contents of '*S'
       when the formatted string would require more than  MAXSIZE  characters.
       Unrecognized  specifiers  and  fields  of  'timp' that are out of range
       cause undefined results.  Since some formats expand to 0 bytes,  it  is
       wise  to  set '*S' to a nonzero value beforehand to distinguish between
       failure and an empty string.  This implementation does not support  's'
       being NULL, nor overlapping 's' and 'format'.

          'strftime' requires no supporting OS subroutines.


          *Bugs* hard-coding the "C" locale settings.



SEE ALSO
       strftime  is  part  of  the libc:_(libc)._the_ansi_c_library.  library.
       The full documentation for libc:_(libc)._the_ansi_c_library.  is  main‐
       tained      as      a      Texinfo     manual.      If     info     and
       libc:_(libc)._the_ansi_c_library.  are properly installed at your site,
       the command

              info libc:_(libc)._the_ansi_c_library.

       will give you access to the complete manual.



NEWLIB                            March 2015                       STRFTIME(3)

[-- Attachment #3: Type: text/plain, Size: 218 bytes --]

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: strftime man page is garbled

[Achim Gratz]

Marco Atzeri writes:
> Works fine for me, I have a complete man page
> see attached.

I think that's exactly what Wayne was talking about:

> DESCRIPTION
>        into a null-terminated string, starting at S and occupying no more than
>        MAXSIZE characters.

The beginning of the sentence seems to be missing, although it looks
like a run-in from the NAME section could be intended.  Also, if you
look at that manpage in a wide terminal you'll see that most paragraphs
have hard formatting, while some flow to the width of the terminal.

Both things are happening on other newlib manpages as well, so it's
probably either the source code for the manpages itself or man doesn't
deal with the slightly odd roff macros from newlib correctly.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf microQ V2.22R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: strftime man page is garbled

[Marco Atzeri]

On 6/4/2015 7:46 AM, Achim Gratz wrote:
> Marco Atzeri writes:
>> Works fine for me, I have a complete man page
>> see attached.
>
> I think that's exactly what Wayne was talking about:
>
>> DESCRIPTION
>>         into a null-terminated string, starting at S and occupying no more than
>>         MAXSIZE characters.
>
> The beginning of the sentence seems to be missing, although it looks
> like a run-in from the NAME section could be intended.  Also, if you
> look at that manpage in a wide terminal you'll see that most paragraphs
> have hard formatting, while some flow to the width of the terminal.
>
> Both things are happening on other newlib manpages as well, so it's
> probably either the source code for the manpages itself or man doesn't
> deal with the slightly odd roff macros from newlib correctly.
>
>
> Regards,
> Achim.
>

you are right.
The man page seems very simple

--------------------------------------------------
.SH DESCRIPTION
'strftime' converts a 'struct tm' representation of the time (at TIMP)
into a null-terminated string, starting at S and occupying no more than
MAXSIZE characters.
--------------------------------------------------

It looks a man-db issue, it misinterprets the ' at the begin
of the phrase.

Adding a single space before works fine.


DESCRIPTION
  'strftime' converts a 'struct tm' representation of the time (at TIMP)
into a null-terminated string, starting at S and occupying no more than
MAXSIZE characters.








--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

RE: strftime man page is garbled

[Nellis, Kenneth]

From: Marco Atzeri
> <snip>
> It looks a man-db issue, it misinterprets the ' at the begin
> of the phrase.
> 
> Adding a single space before works fine.

Perhaps preferred would be to highlight the name with .B:

$ diff -u before after
--- before      2015-06-04 08:37:08.693623000 -0400
+++ after       2015-06-04 08:47:17.078420500 -0400
@@ -10,7 +10,8 @@
          const struct tm *restrict TIMP);

 .SH DESCRIPTION
-'strftime' converts a 'struct tm' representation of the time (at TIMP)
+.B strftime
+converts a 'struct tm' representation of the time (at TIMP)
 into a null-terminated string, starting at S and occupying no more than
 MAXSIZE characters.

$ 

--Ken Nellis

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: strftime man page is garbled

[Jon TURNEY]

On 04/06/2015 14:09, Nellis, Kenneth wrote:
> From: Marco Atzeri
>> <snip>
>> It looks a man-db issue, it misinterprets the ' at the begin
>> of the phrase.
>>
>> Adding a single space before works fine.
>
> Perhaps preferred would be to highlight the name with .B:
>
> $ diff -u before after
> --- before      2015-06-04 08:37:08.693623000 -0400
> +++ after       2015-06-04 08:47:17.078420500 -0400
> @@ -10,7 +10,8 @@
>            const struct tm *restrict TIMP);
>
>   .SH DESCRIPTION
> -'strftime' converts a 'struct tm' representation of the time (at TIMP)
> +.B strftime
> +converts a 'struct tm' representation of the time (at TIMP)
>   into a null-terminated string, starting at S and occupying no more than
>   MAXSIZE characters.
>

It might well be that starting a line with ' is not valid troff markup.

Thanks for the patch.

Unfortunately, the manpages in cygwin-doc are automatically generated 
from the newlib .info pages by a perl script (See newlibinfo2man.pl in [1])

I'm not sure if these man pages are much use now that we have 
man-pages-posix

[1] 
https://github.com/jon-turney/cygwin/commit/f957adfea38022bd3ab076ca77871b53be0ef654


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: strftime man page is garbled

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 772 bytes --]

On 06/04/2015 08:34 AM, Jon TURNEY wrote:

> Unfortunately, the manpages in cygwin-doc are automatically generated
> from the newlib .info pages by a perl script (See newlibinfo2man.pl in [1])
> 
> I'm not sure if these man pages are much use now that we have
> man-pages-posix

GNU/Linux systems have two sections: 'man 3' for system writeup, and
'man 3p' for POSIX pages. This is useful, because in many instances, the
system writeup has more details about Linux-specific extensions, while
the 3p page is more useful for limiting usage to just portable aspects.
 Having both sets shouldn't hurt, if we have a way to easily open from
either set.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: strftime man page is garbled

[Marco Atzeri]

On 6/4/2015 4:34 PM, Jon TURNEY wrote:
> On 04/06/2015 14:09, Nellis, Kenneth wrote:
>> From: Marco Atzeri

>
> It might well be that starting a line with ' is not valid troff markup.

You are right

http://www.gnu.org/software/groff/manual/html_node/Basics.html#Basics

"Not all input lines are text to be formatted. Some input lines are 
requests that describe how to format the text. Requests always have a 
period (‘.’) or an apostrophe (‘'’) as the first character of the input 
line. "

I guess we need to patch upstream...


> Unfortunately, the manpages in cygwin-doc are automatically generated
> from the newlib .info pages by a perl script (See newlibinfo2man.pl in [1])

or check the script

>
> I'm not sure if these man pages are much use now that we have
> man-pages-posix
> [1] https://github.com/jon-turney/cygwin/commit/f957adfea38022bd3ab076ca77871b53be0ef654


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

RE: strftime man page is garbled

[Nellis, Kenneth]

From: Jon TURNEY
> <snip> 
> I'm not sure if these man pages are much use now that we have
> man-pages-posix

It seems the posix pages themselves disagree:
==============8<=============
STRFTIME(3P)               POSIX Programmer's Manual              STRFTIME(3P)

PROLOG
       This  manual page is part of the POSIX Programmer's Manual.  The Cygwin
       implementation of this interface may differ (consult the  corresponding
       Cygwin  manual  page  for details of Cygwin behavior), or the interface
       may not be implemented on Cygwin.

NAME
       strftime, strftime_l — convert date and time to a string
==============>8=============
Indeed Cygwin does not provide the strftime_l function, so the Cygwin pages 
do matter.

--Ken Nellis

Re: strftime man page is garbled

[Jon TURNEY]

On 04/06/2015 02:18, Wayne Pollock wrote:
> The description section of the strftime man page is
> garbled.  The first paragraph shows as this:
>
> =============================
>
>         into a null-terminated string, starting at S and occupying no more than
> MAXSIZE characters.
>
>            You  control the format of the output using the string at FORMAT.
> literally into the formatted string, and
>         time conversion specifications.  Time conversion specifications are two- and
> three-character sequences  begin‐
>         ning  with  ''%'' (use ''%%'' to include a percent sign in the output).  Each
> defined conversion specification
>         selects only the specified field(s) of calendar time data from '*TIMP', and
> converts it to a string in one  of
>         the following ways:
>
> ============================
>
> In addition, none of the option letters show, only the
> option descriptions.  The info node at
> "info libc timefns strftime" appears to be fine.
>
> I have cygwin-doc version 1.7.35-1.
> (I have a locale of C.UTF-8, if it matters.)

Thanks for reporting this issue.

I've uploaded a new cygwin-doc-2.0.3-1 package.

I've tweaked the script which generates these man pages from the newlib 
.info files so it better handles lines starting with a single-quote, and 
also fixing the mess which was being made of the SEE ALSO section.


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: strftime man page is garbled

[Jon TURNEY]

On 04/06/2015 15:50, Eric Blake wrote:
> On 06/04/2015 08:34 AM, Jon TURNEY wrote:
>
>> Unfortunately, the manpages in cygwin-doc are automatically generated
>> from the newlib .info pages by a perl script (See newlibinfo2man.pl in [1])
>>
>> I'm not sure if these man pages are much use now that we have
>> man-pages-posix
>
> GNU/Linux systems have two sections: 'man 3' for system writeup, and
> 'man 3p' for POSIX pages. This is useful, because in many instances, the
> system writeup has more details about Linux-specific extensions, while
> the 3p page is more useful for limiting usage to just portable aspects.
>   Having both sets shouldn't hurt, if we have a way to easily open from
> either set.

Ok.

I don't think the approach of trying to convert the .info is ever going 
to lead to particularly good results, though.  Perhaps this would be 
better implemented as part of newlib, operating on the .texinfo output 
of, or as part of makedoc.


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple