/*
MKDOC.I
Alphabetize DOCUMENT comments and prepare for line printer.
$Id: mkdoc.i,v 1.1 1993/08/27 18:50:06 munro Exp $
*/
/* Copyright (c) 1994. The Regents of the University of California.
All rights reserved. */
func mkdoc (filename, outname, lpp)
/* DOCUMENT mkdoc, filename
or mkdoc, filename, outname, lpp
alphabetizes and indexes the DOCUMENT comments in FILENAME, and
formats into "dictionary-like" pages for printing. If OUTNAME
is not given or nil, the output file will be FILENAME with ".doc"
replacing the ".i". If LPP is not given, it defaults to 58 --
the maximum number of available lines per page of output.
(Use 55 to be able to print with "lpr -p" style page headings.)
FILENAME can be an array of strings to combine several include
files into a single document.
SEE ALSO: help
*/
{
extern mkdoc_lpp;
if (is_void(lpp)) mkdoc_lpp= 58;
else mkdoc_lpp= lpp;
name_list= doc_list= oname= [];
inames= filename;
for (ii=1 ; ii<=numberof(filename) ; ii++) {
f= open(filename(ii));
/* strip off non-directory part of filename */
name= [string(0), filename(ii)];
do {
name= strtok(name(2), "/\:");
} while (name(2));
name= name(1);
inames(ii)= name;
/* get output file name */
if (is_void(oname)) {
if (is_void(outname)) {
oname= name;
if (strpart(oname, -1:0)==".i") oname= strpart(oname, 1:-2);
oname+= ".doc";
} else {
oname= outname;
}
}
/* scan the file to accumulate lists of function/variable/keyword names
and the corresponding document strings */
mkdoc_scan, f;
close, f;
}
/* alphabetize the lists */
order= sort(name_list);
name_list= name_list(order);
doc_list= doc_list(order);
/* make the title page */
f= open(oname, "w");
mkdoc_title, f, inames, name_list;
n= numberof(name_list);
fragment= [];
/* loop on output pages */
while ((nlines= numberof(fragment)) || n) {
nleft= mkdoc_lpp-3; /* leave 3 lines for heading */
if (nlines) {
/* part of the last entry has spilled onto the new page */
if (nlines < nleft) {
/* ...it fits on this page */
page= fragment;
fragment= [];
nleft-= nlines;
} else {
/* ...it fills this page completely, too --
be sure at least 6 lines on next page */
if (nlines < nleft+6) {
page= fragment(1:-6);
fragment= fragment(-5:0);
} else {
page= fragment(1:nleft);
fragment= fragment(nleft+1:0);
}
mkdoc_page, f, name, name, page;
continue;
}
fname= name;
not_top= 1;
} else {
page= [];
fname= name_list(1);
not_top= 0;
}
/* loop on entries for this page */
while (n) {
oname= name;
name= name_list(1);
fragment= *doc_list(1);
nlines= 1+numberof(fragment);
if (nleft >= nlines+not_top) {
/* this entire entry fits on this page */
if (not_top) grow, page, "";
grow, page, swrite(format="%75s", name), fragment;
fragment= [];
nleft-= nlines+not_top;
} else if (nlines+not_top>7 && nleft>7 &&
(nlines-nleft>=6 || nlines>12)) {
/* this entry runs over onto following pages */
if (not_top) grow, page, "";
nleft-= 1+not_top;
if (nlines-nleft<6) nlines-= 6;
else nlines= nleft;
grow, page, swrite(format="%75s", name), fragment(1:nlines);
fragment= fragment(nlines+1:);
nleft= 0;
} else {
/* this entire entry goes on next page */
name= oname;
fragment= [];
break;
}
if (--n) {
name_list= name_list(2:);
doc_list= doc_list(2:);
}
if (nleft<3 || numberof(fragment)) break;
not_top= 1;
}
/* output this page with dictionary headings */
mkdoc_page, f, fname, name, page;
}
close, f;
}
func mkdoc_scan (f)
{
/* Add extern, local, func, and struct declaration/definition names to
the name_list. For extern and func, add the DOCUMENT comment to the
doc_list. If no DOCUMENT comment appears within 10 non-blank lines,
skip to the next extern or func. If subsequent extern lines precede
the DOCUMENT comment, generate a cross-reference SEE ... to the
first extern of the group. For struct, the entire struct definition,
which is presumably commented, becomes the documentation text. */
extern name_list, doc_list;
while (line= rdline(f)) {
split= strtok(line);
doctext= [];
if (split(1)=="func" || split(1)=="extern" || split(1)=="local") {
name= strtok(split(2), " \t(,;");
if (split(1)!="local") crossref= [];
else crossref= mkdoc_cross(1, name(2), []);
name= name(1);
count= 10; /* like help_worker function defined in std.i */
while ((line= rdline(f)) && count--) {
split= strtok(line);
if (!split(1)) break;
if (strmatch(line, "/* DOCUMENT")) {
do {
grow, doctext, [line];
if (strmatch(line, "*/")) break;
} while (line= rdline(f));
} else if (split(1)=="extern") {
crossref= mkdoc_cross(0, split(2), crossref);
if (count==9) count= 10;
} else if (split(1)=="local") {
crossref= mkdoc_cross(1, split(2), crossref);
if (count==9) count= 10;
}
}
} else if (split(1)=="struct") {
name= strtok(split(2), " \t(,;")(1);
gotopen= 0;
do {
grow, doctext, [line];
if (!gotopen) gotopen= strmatch(line, "{");
if (gotopen && strmatch(line, "}")) break;
} while (line= rdline(f));
crossref= [];
}
if (!is_void(doctext)) {
grow, name_list, [name];
grow, doc_list, [&doctext];
n= numberof(crossref);
for (i=1 ; i<=n ; i++) {
grow, name_list, crossref(i);
grow, doc_list, &[" /* SEE "+name+" */"];
}
}
}
}
func mkdoc_cross (loc, names, crossref)
{
split= strtok(names, " \t,;");
cross= crossref;
while (split(1) && !strmatch(split(1), "/*")) {
grow, cross, split(1:1);
if (!loc) break;
split= strtok(split(2), " \t,;");
}
return cross;
}
func mkdoc_title (f, inames, name_list)
{
extern mkdoc_lpp;
write, f, format="\n\n\n"+
" Yorick Documentation\n"+
" for functions, variables, and structures\n"+
" defined in file %s\n"+
" Printed: %s\n", inames(1), timestamp();
write, f, format="\n %s\n\n", "Contents:";
nleft= mkdoc_lpp-10;
n= numberof(name_list);
ncols= 1;
while (n/ncols > nleft-3) ncols++;
width= 80/ncols;
len= max(strlen(name_list));
if (len > width-3) {
/* Contents will overflow onto subsequent page(s). Hopefully rare. */
ncols= 80/(len+3);
width= 80/ncols;
}
format= (width-len)/2 + 1;
width-= format;
format= swrite(format="%"+print(format)(1)+"s", ""); /* leading blanks */
format= format+"%-"+print(width)(1)+"s"; /* e.g.- " %-12s" */
len= (n-1)/ncols + 1;
for (i=1 ; i<=len ; i++) {
line= "";
for (j=i ; j<=n ; j+= len) line+= swrite(format=format, name_list(j));
j= strlen(line);
while (strpart(line, j:j)==" ") j--;
write, f, format="%s", strpart(line, 1:j)+"\n";
}
}
func mkdoc_page (f, fname, name, page)
{
extern mkdoc_lpp;
write, f, format="\f\n%75s\n\n", swrite(format="FROM %s TO %s",
fname, name);
n= numberof(page);
for (i=1 ; i<=n ; i++) write, f, format="%s\n", page(i);
}
