#51: Evaluate documentation format

["atf trac notification" <nobody%julipedia.org@localhost>]

#51: Evaluate documentation format
-------------------+--------------------------------------------------------
 Reporter:  jmmv   |       Owner:  jmmv
     Type:  task   |      Status:  new 
 Priority:  major  |   Milestone:      
Component:  MISC   |     Version:      
 Keywords:         |  
-------------------+--------------------------------------------------------
 Manual pages may be fine for documenting command-line tools, but they do
 not work well to document the API and to provide a more consistent "whole-
 project" document.  They don't scale well: it's impossible to properly
 cross-reference stuff; they are a nightmare to read in their source form;
 and, as they are independent files, they tend to carry a lot of
 repetition.  (Compare atf-c-api(3) and atf-c++-api(3).)

 At last, the ATF manual pages do not "mix well" with other manual pages:
 just take a look at the introductory atf(7) which attempts to be a
 replacement for a proper table of contents, and the huge atf-*-api pages
 which do not have the granularity that manpages should have.

 I do want to have a nicer manual for ATF.  Investigate what the
 alternatives are (Texinfo, Docbook), how to provide a minimum set of
 manual pages and come up with a proposal that doesn't cause much
 complains.

-- 
Ticket URL: <http://www.julipedia.org/projects/atf/trac/ticket/51>
Automated Testing Framework <http://www.NetBSD.org/~jmmv/atf/>
Automated Testing Framework