Re: Documentation on functions
On 9/15/05, Siegfried Heintze wrote: In other words, is the process of submitting documentation documented? Does one use the GNU texi or SGML docbook or some other format? I've been curious about these tools for years but have never used them. It depends on what you're documenting. As Eric noted, for libc functions you submit a patch to the newlib mailing list and then it trickles into Cygwin via my cygwin-doc package. For the Cygwin-specific functions, the documentation is in the Cygwin CVS http://cygwin.com/cvs.html and is written in XML DocBook. Unfortunately there have been no updates to this documentation in a long time, I would love to see more. (And, if you want to learn more about DocBook, I recommend the in-progress Fedora Documentation Guide http://fedora.redhat.com/participate/documentation-guide/ --obviously there are differences in Cygwin specifics but introduction to the tools and the parts about the tags and style are very helpful.) Is it a simple matter of cutting and pasting from linux (e.g. fedora) man pages or does one have to go to the source code and extract the copious comments there and just reformat them into man pages? As others have noted, Cygwin usually tries for POSIX conformance so the Linux man pages are usually good enough but might disagree at times. I suppose I should build some sort of placeholder man pages pointing to the POSIX website. Anybody want to write a script to do it? -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
RE: Documentation on functions
Is there documentation on the documentation? In other words, is the process of submitting documentation documented? Does one use the GNU texi or SGML docbook or some other format? I've been curious about these tools for years but have never used them. Are there any functions documented (and I just had the bad luck of picking the only three that were not documented) or do they all need to be documented? (Yikes! That could be a big job)! Is it a simple matter of cutting and pasting from linux (e.g. fedora) man pages or does one have to go to the source code and extract the copious comments there and just reformat them into man pages? Siegfried -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
RE: Documentation on functions
Siegfried Heintze wrote: Is there documentation on the documentation? In other words, is the process of submitting documentation documented? Does one use the GNU texi or SGML docbook or some other format? I've been curious about these tools for years but have never used them. Are there any functions documented (and I just had the bad luck of picking the only three that were not documented) or do they all need to be documented? (Yikes! That could be a big job)! Is it a simple matter of cutting and pasting from linux (e.g. fedora) man pages or does one have to go to the source code and extract the copious comments there and just reformat them into man pages? Siegfried $ man -w /usr/local/man:/usr/share/man:/usr/local/pgsql/man:/usr/X11R6/man:/usr/s sl/man:/usr/man WS-XP-4960: /home/rthompso $ ls /usr/local/man/* /usr/local/man/ja: man1 /usr/local/man/man1: ascii-xfr.1 cscope.1 evim.1 gvimdiff.1 lua.1 mplayer.1 ratpoison.1 rview.1 sclite.1 vimdiff.1 wterm.1 aterm.1 dig.1 ex.1 host.1 luac.1 mrxvt.1 rgview.1 rvim.1 script.1 vimtutor.1 xminicom.1 blackbox.1 elinks.1 fontforge.1 imlib-config.1 mencoder.1 namazu.1 rgvim.1 rvimdiff.1 sfddiff.1 w3m.1 xmms.1 bsetbg.1 ervim.1 gview.1 imlib_config.1 minicom.1 nslookup.1 rover.1 rvimtutor.1 view.1 w3mman.1xxd.1 bsetroot.1 eview.1 gvim.1 links2.1mknmz.1 osd_cat.1 runscript.1 sc_stats.1 vim.1 wmxmms.1 /usr/local/man/man3: lwres.3lwres_conf_parse.3 lwres_gai_strerror.3lwres_gnbaresponse_render.3 lwres_addr_parse.3 lwres_conf_print.3 lwres_getaddrinfo.3 lwres_herror.3 lwres_buffer.3 lwres_config.3 lwres_getaddrsbyname.3 lwres_hstrerror.3 lwres_buffer_add.3 lwres_context.3 lwres_gethostbyaddr.3 lwres_inetntop.3 lwres_buffer_back.3lwres_context_allocmem.3 lwres_gethostbyaddr_r.3 lwres_lwpacket_parseheader.3 lwres_buffer_clear.3 lwres_context_create.3 lwres_gethostbyname.3 lwres_lwpacket_renderheader.3 lwres_buffer_first.3 lwres_context_destroy.3 lwres_gethostbyname2.3 lwres_net_ntop.3 lwres_buffer_forward.3 lwres_context_freemem.3 lwres_gethostbyname_r.3 lwres_noop.3 lwres_buffer_getmem.3 lwres_context_initserial.3 lwres_gethostent.3 lwres_nooprequest_free.3 lwres_buffer_getuint16.3 lwres_context_nextserial.3 lwres_gethostent_r.3lwres_nooprequest_parse.3 lwres_buffer_getuint32.3 lwres_context_sendrecv.3 lwres_getipnode.3 lwres_nooprequest_render.3 lwres_buffer_getuint8.3lwres_endhostent.3 lwres_getipnodebyaddr.3 lwres_noopresponse_free.3 lwres_buffer_init.3lwres_endhostent_r.3 lwres_getipnodebyname.3 lwres_noopresponse_parse.3 lwres_buffer_invalidate.3 lwres_freeaddrinfo.3 lwres_getnamebyaddr.3 lwres_noopresponse_render.3 lwres_buffer_putmem.3 lwres_freehostent.3 lwres_getnameinfo.3 lwres_packet.3 lwres_buffer_putuint16.3 lwres_gabn.3 lwres_getrrsetbyname.3 lwres_resutil.3 lwres_buffer_putuint32.3 lwres_gabnrequest_free.3 lwres_gnba.3 lwres_sethostent.3 lwres_buffer_putuint8.3lwres_gabnrequest_parse.3 lwres_gnbarequest_free.3lwres_sethostent_r.3 lwres_buffer_subtract.3lwres_gabnrequest_render.3 lwres_gnbarequest_parse.3 lwres_string_parse.3 lwres_conf_clear.3 lwres_gabnresponse_free.3 lwres_gnbarequest_render.3 xosd.3 lwres_conf_get.3 lwres_gabnresponse_parse.3 lwres_gnbaresponse_free.3 lwres_conf_init.3 lwres_gabnresponse_render.3 lwres_gnbaresponse_parse.3 /usr/local/man/man5: elinks.conf.5 elinkskeys.5 named.conf.5 rndc.conf.5 /usr/local/man/man8: dnssec-keygen.8lft.8 mtr.8 named-checkzone.8 named.conf.5 rndc-confgen.8 dnssec-signzone.8 lwresd.8 named-checkconf.8 named.8 nsupdate.8rndc.8 WS-XP-4960: /home/rthompso $ ls /usr/share/man/* /usr/share/man/bg: man1 man5 /usr/share/man/cat1: fltk-config.1 fluid.1 /usr/share/man/cat3: fltk.3 /usr/share/man/cs: man1 man5 /usr/share/man/da: man1 man5 /usr/share/man/de: man1 man5 man6 /usr/share/man/el: man1 man5 man8 /usr/share/man/es: man1 man5 /usr/share/man/fi: man1 man5 /usr/share/man/fr: man1 man5 man6 /usr/share/man/hr: man1 man5 /usr/share/man/it: man1 man5 man6 man8 /usr/share/man/ja: man1 man5 /usr/share/man/ko: man1 man5 /usr/share/man/man1: GraphicsMagick++-config.1 djpeg.1head.1.gz oggenc.1splitdiff.1.gz GraphicsMagick-config.1dlltool.1 help.1 ogginfo.1 sprut.1 ImageMagick.1 do.1 help2man.1.gz oka.1 ssh-add.1 Magick++-config.1 done.1 history.1 onsgmls.1.gzssh-agent.1 Magick-config.1doxygen.1.gz hostid.1.gz
RE: Documentation on functions
Is there documentation on the documentation? In other words, is the process of submitting documentation documented? Does one use the GNU texi or SGML docbook or some other format? I've been curious about these tools for years but have never used them. A while ago (Feb 05, if you are trying to see the changes in newlib CVS), I documented newlib's strftime (well, improved the existing documentation) when I added all the remaining bits required to become POSIX compliant. I did this by checking the newlib sources out of CVS, then edited newlib/libc/time/strftime.c and other files, and submitted the patch to the newlib mailing list, where it was accepted. A while later, once a subsequent cygwin documentation release was made, man strftime (as well as info strftime) had my doc edits! For newlib documentation, the documentation is embedded inline in the C files, plus a couple of glue .tex files, which are then processed during the newlib build by texinfo to create the documentation. I just followed the existing styles, so strftime.c is an example you can use when adding documentation to functions that have none. I'm not sure about adding cygwin function documentation. Are there any functions documented (and I just had the bad luck of picking the only three that were not documented) or do they all need to be documented? (Yikes! That could be a big job)! Is it a simple matter of cutting and pasting from linux (e.g. fedora) man pages or does one have to go to the source code and extract the copious comments there and just reformat them into man pages? Don't just steal documentation from fedora, as it is likely to be wrong. But it can be a good starting point. newlib is different from glibc, and not all things work the same between the systems. It takes effort to document actual behavior. Also, editing man pages directly is useless, because the format is so archaic, and because man pages are usually generated from an upstream format (like texinfo). -- Eric Blake -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
Re: Documentation on functions
I noticed that when I boot fedora core 4, the function readdir is documented in man. However, when I boot windows/Cygwin readdir is not available in info or man. When I download the same code for Beginning Programming in Linux from the www.wrox.com site I notice that all the code on pthreads compiles and seems to run! But, I notice, pthread_attr_init is not in man or info either. Where is the documentation on these functions? Missing because no one has ever contributed it. http://cygwin.com/acronyms#PTC -- Eric Blake -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
Re: Documentation on functions
I noticed that when I boot fedora core 4, the function readdir is documented in man. However, when I boot windows/Cygwin readdir is not available in info or man. When I download the same code for Beginning Programming in Linux from the www.wrox.com site I notice that all the code on pthreads compiles and seems to run! But, I notice, pthread_attr_init is not in man or info either. Where is the documentation on these functions? Missing because no one has ever contributed it. http://cygwin.com/acronyms#PTC Followup - for standard functions, like readdir or pthread_attr_init, I usually refer directly to POSIX (http://www.opengroup.org/onlinepubs/009695399/toc.htm) to at least see what aspects of the function should be implemented across various systems, although it doesn't document the extensions that are permitted. For non-standard functions, google is your friend (for example, I recently patched newlib's argz_insert, which was not behaving like BSD's version; googling for 'man argz_insert' was what let me find out how BSD does it, since POSIX does not require it). Furthermore, some of the lack of documentation is the fault of newlib, not cygwin, but both projects could use improvements. -- Eric Blake -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
RE: Documentation on functions
Siegfried Heintze wrote: This is the third time I have mailed this to Cygwin@cygwin.com and it has not showed up yet in the list. I am subscribed. Obviously, if you are seeing this, then it succeeded. What a mystery. Anyway... I noticed that when I boot fedora core 4, the function readdir is documented in man. However, when I boot windows/Cygwin readdir is not available in info or man. When I download the same code for Beginning Programming in Linux from the www.wrox.com site I notice that all the code on pthreads compiles and seems to run! But, I notice, pthread_attr_init is not in man or info either. Where is the documentation on these functions? Thanks, Siegfried/ http://www.die.net/doc/linux/man/man3/readdir.3.html http://www.die.net/doc/linux/man/ reid -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
RE: Documentation on functions
Eric Blake wrote: Followup - for standard functions, like readdir or pthread_attr_init, I usually refer directly to POSIX (http://www.opengroup.org/onlinepubs/009695399/toc.htm) to at great pointer -- thanks reid -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
Re: Documentation on functions
On Wed, Sep 14, 2005 at 08:26:30AM -0600, Siegfried Heintze wrote: This is the third time I have mailed this to Cygwin and it has not showed up yet in the list. I am subscribed. Obviously, if you are seeing this, then it succeeded. What a mystery. Two bounce messages were sent to you: Tue Sep 13 04:49:21 2005 8597603 from: siegfried to: cygwin status: failure: Invalid_mime_type_text/html_detected_in_message_text_or_attachment./Please_send_plain_text_messages_only./See_http://sourceware.org/lists.html#sourceware-list-info_for_mailing_list/info_for_this_site./Contact_cygwin-owner-AT-cygwin.com_if_you_have_questions_about_this._(#5.7.2)/ Wed Sep 14 03:34:48 2005 8840885 from: siegfried to: cygwin status: failure: Invalid_mime_type_text/html_detected_in_message_text_or_attachment./Please_send_plain_text_messages_only./See_http://sourceware.org/lists.html#sourceware-list-info_for_mailing_list/info_for_this_site./Contact_cygwin-owner-AT-cygwin.com_if_you_have_questions_about_this._(#5.7.2)/ http://cygwin.com/ml/#html-mail cgf -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
RE: Documentation on functions
From: Siegfried Heintze Sent: Wednesday, September 14, 2005 9:27 AM To: cygwin@cygwin.com Subject: Documentation on functions This is the third time I have mailed this to Cygwin@cygwin.com and it has not showed up yet in the list. I am subscribed. Obviously, if you are seeing this, then it succeeded. Sorry, it still didn't work. -- Gary R. Van Sickle PS: I AM HI-LARIOUS!!! ;-) -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
Re: Documentation on functions
On Wed, Sep 14, 2005 at 08:01:24PM -0500, Gary R. Van Sickle wrote: From: Siegfried Heintze Sent: Wednesday, September 14, 2005 9:27 AM Subject: Documentation on functions This is the third time I have mailed this to Cygwin and it has not showed up yet in the list. I am subscribed. Obviously, if you are seeing this, then it succeeded. Sorry, it still didn't work. I don't know. I think it almost worked. I could have sworn I saw something. Maybe it was just my imagination. cgf -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Problem reports: http://cygwin.com/problems.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/
