| [AD] chapters for devhelp documentation |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
The attached patch is a quick hack to add @chapter and @endchapter
commands to makedoc. (Yes, I know, adding another hack to makedoc isn't
the best idea :)
What it does is adding another level to the devhelp TOC hierarchy -
which really makes them a lot more useable. About all other devhelp docs
have a deeper hierarchy than Allegro (including the SDL ones) - and the
Allegro docs really were very hard to navigate with their multiple-
pages-long TOC. Since I'm probably the only one using devhelp, here's a
screenshot what the Allegro docs look like in devhelp with the patch:
http://allefant.sourceforge.net/allegro/Screenshot-9.png
Before, it was just one long list of headings. Now most headings are in
one of the 3 chapters "API", "Platform specifics" and "Miscellaneous".
API actually still contains too many entries, so at some point it should
probably be grouped into "graphics", "sound", and so on.. but I'm not
going to add another hierarchy level into makedoc right now :P
This shouldn't have any effect on other output formats (I set the last 3
params of _add_toc_line() to 0 - that should disable everything,
right?). Oh, and I also removed the "btoc_prev" variable from makedevh.c
since it seemed unused.
--
Elias Pschernig
? chapters.diff
Index: src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.253
diff -u -p -r1.253 allegro._tx
--- src/allegro._tx 3 Sep 2004 11:50:46 -0000 1.253
+++ src/allegro._tx 5 Sep 2004 16:15:57 -0000
@@ -82,6 +82,8 @@ Contents
@text
@externalfile readme A general introduction to Allegro
+@chapter
+API
@heading
Using Allegro
@@ -8658,6 +8660,8 @@ ensure there is room for the check.
@!man
+@chapter
+Platform specifics
@heading
DOS specifics
@@ -9905,6 +9909,8 @@ insulate you from some of the difference
+@chapter
+Miscellaneous
@headingnocontent
Reducing your executable size
@@ -11145,6 +11151,7 @@ and avoid missing any important bit of i
@externalfile ahack The Allegro hacker's guide
@externalfile const Allegro `const'-correctness
@externalfile packfile Packfile format information
+@endchapter
@headingnocontent
Conclusion
Index: src/makedoc/makedevh.c
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/makedoc/makedevh.c,v
retrieving revision 1.2
diff -u -p -r1.2 makedevh.c
--- src/makedoc/makedevh.c 15 May 2003 22:51:26 -0000 1.2
+++ src/makedoc/makedevh.c 5 Sep 2004 16:16:17 -0000
@@ -32,13 +32,13 @@
#include "makedoc.h"
#define ALT_TEXT(toc) ((toc->alt) ? toc->alt : toc->text)
-#define PREV_ROOT 1
-#define PREV_SUB 2
+enum PREV { PREV_NO, PREV_ROOT, PREV_SUB, PREV_CHAP };
+enum TYPE { TYPE_ROOT1, TYPE_ROOT2, TYPE_SUB1, TYPE_SUB2, TYPE_FUNC };
/* Buffered tocs. Only the 'local' pointer should be freed */
typedef struct BTOC
{
- int type;
+ enum TYPE type;
const char *name;
char *local;
} BTOC;
@@ -46,7 +46,7 @@ typedef struct BTOC
extern const char *html_extension;
static void _write_object(FILE *file, const char *name, const char *local, int open);
-static void _output_btoc(FILE *file, BTOC *btoc, int *btoc_prev, int *num_btoc);
+static void _output_btoc(FILE *file, BTOC *btoc, int *num_btoc);
static int _qsort_btoc_helper(const void *e1, const void *e2);
@@ -55,15 +55,14 @@ static int _qsort_btoc_helper(const void
* Sorts all the buffered tocs read so far and frees their memory after
* writting them to the file. Can be safely called at any moment, as long
* as the pointer to num_btoc is meaningfull and contains the number of
- * buffered tocs in the btoc table. Note that btoc_prev is NOT sorted.
+ * buffered tocs in the btoc table.
*/
-static void _output_btoc(FILE *file, BTOC *btoc, int *btoc_prev, int *num_btoc)
+static void _output_btoc(FILE *file, BTOC *btoc, int *num_btoc)
{
int num;
assert(btoc);
assert(num_btoc);
- assert(btoc_prev);
qsort(btoc, *num_btoc, sizeof(BTOC), _qsort_btoc_helper);
@@ -99,10 +98,34 @@ static void _write_object(FILE *file, co
assert(file);
assert(name);
assert(local);
-
+
fprintf(file, "%s name=\"%s\" link=\"%s\"%s>\n",
- type == 0 ? " <sub" : type == 1 ? " <sub" : " <function",
- name, local, type ? "/" : "");
+ type == TYPE_ROOT1 ? " <sub" :
+ (type == TYPE_SUB1 || type == TYPE_ROOT2) ? " <sub" :
+ type == TYPE_SUB2 ? " <sub" : " <function",
+ name, local, (type == TYPE_ROOT1 || type == TYPE_ROOT2) ? "" : "/");
+}
+
+
+
+static char *devhelp_blank_page(char const *name, char const *filename, int num)
+{
+ char str[256];
+ char *path;
+ sprintf(str, "chapter%i.html", num);
+ path = m_replace_filename (filename, str);
+ printf("Writing %s.\n", path);
+ FILE *file = fopen(path, "w");
+ if (file) {
+ /* Ideally, this would use Allegro's common HTML style and header
+ and footer. */
+ fprintf(file, "<html>\n<head><title>%s</title></head>\n<body>\n", name);
+ fprintf(file, "<h1>%s</h1>", name);
+ fprintf(file, "<p>Use the table of contents to navigate through this chapter.");
+ fprintf(file, "</body>\n</html>\n");
+ fclose(file);
+ }
+ return path;
}
@@ -115,9 +138,11 @@ int write_devhelp(const char *filename)
FILE *file;
TOC *toc;
char *dest_name;
- int btoc_prev[TOC_SIZE];
- int section_number = -1, prev = 0, num_btoc = 0;
-
+ int section_number = -1, num_btoc = 0;
+ enum PREV prev = PREV_NO;
+ int in_chapter = 0;
+ int chapter_num = 1;
+
if (!strcmp(get_extension(filename), "htm"))
html_extension = "html";
@@ -137,7 +162,7 @@ int write_devhelp(const char *filename)
fprintf(file, " link=\"allegro.html\">\n");
fprintf(file, "\n");
fprintf(file, "<chapters>\n");
-
+
toc = tochead;
if (toc)
toc = toc->next;
@@ -145,16 +170,27 @@ int write_devhelp(const char *filename)
for (; toc; toc = toc->next) {
char name[256];
- if (toc->htmlable) {
- if (toc->root) {
+ if (toc->htmlable || toc->root > 1) {
+ if (toc->root ) {
+
+ /* Write previous section. */
+ _output_btoc(file, btoc, &num_btoc);
- _output_btoc(file, btoc, btoc_prev, &num_btoc);
- if (prev == PREV_SUB)
- fprintf(file, " </sub>\n");
- if (prev == PREV_ROOT)
- fprintf(file, " </sub>\n");
+ if (prev == PREV_ROOT || prev == PREV_SUB)
+ fprintf(file, "%s</sub>\n", in_chapter ? " " : " ");
- if (toc->otherfile) {
+ if (toc->root == 2 || toc->root == 3) {
+ if (in_chapter)
+ fprintf(file, " </sub>\n");
+ if (toc->root == 2) {
+ char *path;
+ path = devhelp_blank_page(ALT_TEXT(toc), filename, chapter_num++);
+ strcpy(name, get_filename(path));
+ free(path);
+ }
+ in_chapter = 0;
+ }
+ else if (toc->otherfile) {
sprintf(name, "%.240s.%.10s", toc->text, html_extension);
}
else {
@@ -162,31 +198,40 @@ int write_devhelp(const char *filename)
get_section_filename(name, filename, section_number);
}
- prev = PREV_ROOT;
+ if (toc->root == 3) {
+ prev = PREV_NO;
+ }
+ else {
+
+ prev = toc->root == 1 ? PREV_ROOT : PREV_CHAP;
+
+ _write_object(file, ALT_TEXT(toc), name, in_chapter ? TYPE_ROOT2 : TYPE_ROOT1);
- _write_object(file, ALT_TEXT(toc), name, 0);
+ if (toc->root == 2)
+ in_chapter = 1;
+ }
}
else {
- btoc_prev[num_btoc] = prev;
-
get_section_filename(name, filename, section_number);
strcat(name, "#");
strcat(name, toc->text);
prev = PREV_SUB;
-
+
/* Buffer toc for posterior output */
- btoc[num_btoc].type = 1;
+ btoc[num_btoc].type = in_chapter ? TYPE_SUB2 : TYPE_SUB1;
btoc[num_btoc].local = m_strdup(name);
btoc[num_btoc++].name = ALT_TEXT(toc);
}
}
}
- _output_btoc(file, btoc, btoc_prev, &num_btoc);
+ _output_btoc(file, btoc, &num_btoc);
- if (prev == PREV_ROOT)
+ if (prev == PREV_SUB || prev == PREV_ROOT)
+ fprintf(file, "%s</sub>\n", in_chapter ? " " : " ");
+ if (in_chapter)
fprintf(file, " </sub>\n");
fprintf(file, "</chapters>\n");
@@ -209,12 +254,12 @@ int write_devhelp(const char *filename)
get_section_filename(name, filename, section_number);
strcat(name, "#");
strcat(name, toc->text);
- btoc[num_btoc].type = 2;
+ btoc[num_btoc].type = TYPE_FUNC;
btoc[num_btoc].local = m_strdup(name);
btoc[num_btoc++].name = ALT_TEXT(toc);
}
}
- _output_btoc(file, btoc, btoc_prev, &num_btoc);
+ _output_btoc(file, btoc, &num_btoc);
fprintf(file, "</functions>\n");
fprintf(file, "\n");
Index: src/makedoc/makedoc.c
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/makedoc/makedoc.c,v
retrieving revision 1.17
diff -u -p -r1.17 makedoc.c
--- src/makedoc/makedoc.c 5 Aug 2004 08:18:18 -0000 1.17
+++ src/makedoc/makedoc.c 5 Sep 2004 16:16:17 -0000
@@ -364,6 +364,11 @@ static int _read_file(char *filename)
flags |= (HEADING_FLAG | NOCONTENT_FLAG);
else if (mystricmp(buf+1, "heading") == 0)
flags |= HEADING_FLAG;
+ else if (mystricmp(buf+1, "chapter") == 0)
+ flags |= CHAPTER_FLAG;
+ else if (mystricmp(buf+1, "endchapter") == 0) {
+ _add_toc_line(buf, NULL, 3, line, 0, 0, 0);
+ }
else if (mystricmp(buf+1, "retval") == 0) {
_add_line("", flags | RETURN_VALUE_FLAG);
flags &= ~(HEADING_FLAG | NOCONTENT_FLAG | NONODE_FLAG);
@@ -515,10 +520,14 @@ static int _read_file(char *filename)
}
else {
/* some actual text */
+ if (flags & CHAPTER_FLAG)
+ _add_toc_line(buf, NULL, 2, line, 0, 0, 0);
+
if (flags & HEADING_FLAG)
_add_toc(buf, 1, line, !(flags & NONODE_FLAG), (flags & HTML_FLAG));
- _add_line(buf, flags);
+ if (!(flags & CHAPTER_FLAG))
+ _add_line(buf, flags);
if (_warn_on_long_lines) {
int len = strlen (buf);
@@ -527,7 +536,7 @@ static int _read_file(char *filename)
line, len - 77, buf + 77);
}
- flags &= ~(HEADING_FLAG | NOCONTENT_FLAG | NONODE_FLAG);
+ flags &= ~(CHAPTER_FLAG | HEADING_FLAG | NOCONTENT_FLAG | NONODE_FLAG);
}
}
@@ -674,7 +683,7 @@ static void _add_toc(char *buf, int root
int got;
if (root) {
- _add_toc_line(buf, NULL, 1, num, texinfoable, htmlable, 0);
+ _add_toc_line(buf, NULL, root, num, texinfoable, htmlable, 0);
strcpy(b, buf);
sprintf(buf, "<a name=\"%s\">%s</a>", b, b);
}
Index: src/makedoc/makedoc.h
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/makedoc/makedoc.h,v
retrieving revision 1.5
diff -u -p -r1.5 makedoc.h
--- src/makedoc/makedoc.h 14 Apr 2003 09:04:25 -0000 1.5
+++ src/makedoc/makedoc.h 5 Sep 2004 16:16:17 -0000
@@ -33,6 +33,7 @@
#define MANGLE_EMAILS 0x08000000
#define RETURN_VALUE_FLAG 0x10000000
#define EREF_FLAG 0x20000000
+#define CHAPTER_FLAG 0x40000000
#define TOC_SIZE 8192