#33 Add man pages

GC 2.2
closed
None
6
2017-08-28
2014-08-25
No

It would be good to generate them, too.
Attached are: a patch for the first shot, leading to these man pages for cobc and cobcrun (both created via help2man). You can test them after download via

man ./cobc.1
man ./cobcrun.1

I'd really like to add these for GC 2.0 release (at least cobc.1 and cobcrun.1).

Open Issues:

  • cobc.1: the indent for -std is broken and unreadable
  • cobcrun.1: bettering the copyright information (it includes the information of libcob, which is fine, but it looks a little ugly)
  • libcob.3: missing completely (anyone up for this?)
  • all manpages: maybe generate them to /doc
  • side-note: reviewing/bettering the info document as we refer to it
  • missing information (any thoughts)?

Simon

3 Attachments

Related

Discussion: Texinfo for GnuCOBOL info help pages
Discussion: GNU Cobol website at http://www.gnu.org/software/gnucobol/

Discussion

  • Brian Tiffin

    Brian Tiffin - 2014-08-26

    I'm in. ;-)

    Thanks, Luke, Simon.

    And sorry this fell to you, (although, not really, the more the merrier). I did an original OpenCOBOL pass a few years back, just never got to the commit. http://www.opencobol.org/modules/newbb/viewtopic.php?topic_id=1436&forum=1#forumpost7377

    I've looked a few times, at adding the man1_MANS targets, tried it on an older machine back then, builds worked fine. The first public test of the dist tarball, in front of strangers, ... fail. Ummm, not properly configured for ./configure. ;-)

    Gun shy, ever since, with the autotools. It's technical voodoo (huge knowledge base), fragile, and requires access to a few different platforms for testing. (Aside; we have a getopts dependency now, lib/cobgetopt.c isn't transferred properly during out of tree builds, passes ./configure, fails make, until the file is hand copied into the correct (out of tree) subdir. This will bork almost all automated distro package builder passes.) (I see no fault, no foul in this; voodoo, delicate, snarky, voodoo). And I have no doubt we can get it beat down when time comes. Fastest way is put it in the cobc/ dir, or libcob/ if it might end up in applications as part of an LGPL runtime.

    Back on topic; once man pages get into the source tree, I'll be more than happy to start adding content and helping keep things in sync with the --help). (It might be smart to have a minimal, focused, man cobc (cobcrun, cob-config), with a link to a more wordy version that gets into COBOL verbs, or the more intricate build potentials when programming in the large, or foreign functions interfacing, etc.

    Simon; you likely know more about the translation side of things; we should poke and pester the volunteers too. (I might be able to convince someone to help with French, at least for three minimal pages.)

    Cheers,
    Brian

     
  • Simon Sobisch

    Simon Sobisch - 2014-08-26

    Hm, did you viewed the attached man pages? What "missing bits" did you add earlier?

    I'll try to always generate them, currently it's 100% help2man, we may add information from other sources. All of the sources that are generated have a translation, therefore it doesn't need to be done another time (as long as the languages are fine [... still have this on my Todo-list..., I've already received translations for FR + NL and do DE on my own - together with bettering the messages] - these are the only files that will need translation)...

    The most interesting question is: where do we get the information for libcob? We may will need a new translation file for this..

    The man targets seem to work quite well (are part of the above patches), I'll de-voodoo the autotools stuff "soon" (I guess you know this could be 1 day or 1 month).

    Simon

     
    • Simon Sobisch

      Simon Sobisch - 2014-12-05

      Committed manpage generation and installation with [r430], libcob still missing (see later posts).

      Simon

       

      Related

      Commit: [r430]

  • Luke Smith

    Luke Smith - 2014-08-26

    (It might be smart to have a minimal, focused, man cobc (cobcrun, cob-config), with a link to a more wordy version that gets into COBOL verbs, or the more intricate build potentials when programming in the large, or foreign functions interfacing, etc.

    Yes, I agree. I'm thinking that when anybody adds features to GNU Cobol, they should also update the info pages with the same commit. There should only be one info page updated by them.

    I do not like the idea of everyone having to update info pages and then man pages too. That would cause lots of problems and they would never be in sync.

    The man page should be auto generated and be minimal.

    The info pages should be updated by everyone and have all of the details.

     
  • Luke Smith

    Luke Smith - 2014-09-22

    I'm reviewing Texinfo to learn how to create info pages.

    Does GNUCOBOL have Texinfo page(s) somewhere in svn? If not, I'd like to start one.

    Since I'm just learning Texinfo, I can't promise that the first cut would be complete or even extensive. But once it's begun, it will be there so that others can add to it if they wish.

     
    Last edit: Luke Smith 2014-09-22
  • Luke Smith

    Luke Smith - 2014-09-26

    Here is a first draft of the chapters in Texinfo. Any suggestions?

    Getting started
       How to install
          Pre-compiled packages
          Version in development
             Subversion (svn) download
       Hello world
       Support
    
    Running programs
       cobc
       cobcrun
    
    Documentation
       GnuCOBOL Programmer's guide
       Recommended books
       How to update this document
    
    Sample programs
       Hello world
       Games
       Applications
    
    Extensions and not ISO/ANSI standard
       SELECT ASSIGN TO
       Indexed file packages
          db
          vbisam
       Extended ACCEPT and DISPLAY
       C functions
    
    Subroutines
       Calling C from COBOL
       Calling COBOL from C
    
    Libraries
       libcob
    
    Support
       GnuCOBOL at Sourceforge
          Discussion forums
          Reporting bugs
       Add1tocobol
       Adding features to GnuCOBOL
    
    GnuCOBOL copyright
    
     
  • Simon Sobisch

    Simon Sobisch - 2014-12-05

    Still pending as feedback is missing and there is no manpage for libcob - if possible we should generate one with the exported functions @Brian (Tiffin): likely something your doxygen / comments stuff could help with.

    Simon

     
  • Simon Sobisch

    Simon Sobisch - 2014-12-05
    • status: open --> pending
    • assigned_to: Simon Sobisch
     
  • Simon Sobisch

    Simon Sobisch - 2017-08-28
    • status: pending --> closed
     
  • Simon Sobisch

    Simon Sobisch - 2017-08-28

    No more responses so far, man pages added by help2man.
    man page for libcob would be very useful but needs a manual approach. We can add a ticket when someone wants to create it...

     

Log in to post a comment.