UNIVERS  15.3
UNIVERS base processing software API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
helpdoc.h
1 /* helpdoc.h */
2 /* $Id: helpdoc.h,v 1.6 2006/01/12 12:02:07 shurik Exp $ */
3 #ifndef __helpdoc_h
4 #define __helpdoc_h
5 
6 /***********************************************************************
7  *
8  * Context help subsystem
9  *
10  ***********************************************************************/
11 
12 #include <mix/Types.h>
13 #include <mix/wenv.h>
14 #include <mix/trans.h>
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif /* __cplusplus */
19 
20 /***********************************************************************
21  * File description constants
22  ***********************************************************************/
23 
24 /* Version of the file format */
25 #define CHA_FORMAT "format"
26 #define CHA_FORMAT_ID "1.2"
27 
28 /* Keywords */
29 #define CHC_COMMENT '#'
30 #define CHC_COMMAND '@'
31 #define CH_MAGIC "@help"
32 #define CH_VERSION "@version"
33 #define CH_TITLE "@title"
34 #define CH_SECTION "@section"
35 #define CH_LOCALREF "@localref"
36 #define CH_GLOBALREF "@globalref"
37 #define CH_INCLUDE "@include" /* 1.1 */
38 #define CH_EXECUTE "@execute" /* 1.2 */
39 
40 
41 /***********************************************************************
42  * Storage for help document
43  ***********************************************************************/
44 
45 /* Reference kind */
46 typedef enum
47 {
48  chLocalRef, /* reference inside document */
49  chGlobalRef, /* global reference to HTML document */
50  chExecute /*execute some program ALEX ZAZNOBIN MODIFY */
51 } ChRefKind;
52 
53 /* Reference item */
54 typedef struct ChRefTag
55 {
56  char *link; /* reference to name/path (NON-LOCALIZED) */
57  char *title; /* description text line */
58  ChRefKind kind; /* kind of link interpretation */
59  struct ChRefTag *next; /* facilitate list of ref. construction */
60 
61 } ChReference;
62 
63 /* Storage for the help section */
64 typedef struct ChSectTag
65 {
66  char *label; /* label of the section (NON-LOCALIZED) */
67  char *title; /* title of the section */
68  char *text; /* context help text */
69  ChReference *ref_list; /* head of references list */
70  struct ChSectTag *next; /* facilitate list of sections construction */
71 
72 } ChSection;
73 
74 /* Storage for the whole help file */
75 typedef struct
76 {
77  char *name; /* name of the document (=weAppName())
78  * (ASCII string) */
79  char *title; /* title of the whole help document */
80  char *version; /* help document version (ASCII string) */
81  char *lang; /* see weGetPrefLanguage() (ASCII string) */
82  TextEncoding tenc; /* encoding for text, titles and labels */
83  ChSection *section_list; /* head of sections list */
84  ChSection *the_section; /* current section pointer or NULL */
85  char *base_dir; /* base directory (ASCII string) */
86 
87 } ChDocument;
88 
89 /* Storage with service info while reading document */
90 typedef struct
91 {
92  int linumber; /* line number: 1,2,3... */
93  Logic title_was; /* title string is already set */
94  Logic version_was; /* version string is already set */
95 
96 } ChReadDocEnv;
97 
98 
99 /***********************************************************************
100  * Top functions
101  ***********************************************************************/
102 
103 /* Load help for given program and given language (NULL means system
104  default language) */
105 ChDocument* chLoadProgramHelp (const char* name, const char* req_lang);
106 
107 /* Load additional help to the same document. */
108 ChDocument* chAddProgramHelp (ChDocument* pDoc,
109  const char* name, const char* req_lang);
110 
111 /* Get list of languages for which help files are defined. */
112 void chProgramHelpLangs (const char* name,
113  int* lang_n, char*** langs);
114 
115 /***********************************************************************
116  * I/O operations
117  ***********************************************************************/
118 
119 /* Load help from given document */
120 ChDocument* chLoadHelpFile (ChDocument* pExDoc, const char* name,
121  const char* basedir, const char* fname);
122 
123 /* Store help to given document */
124 void chSaveHelpFile (ChDocument* pDoc, const char* path);
125 
126 /* Parse the line from given pointer until '\n' or '\0'.
127  Returns pointer to the next line or to '\0' character. */
128 char* chParseLineFromHelpFile (ChDocument* pDoc, char* line,
129  ChReadDocEnv* pEnv);
130 
131 
132 /***********************************************************************
133  * Add contents to help
134  ***********************************************************************/
135 
136 /* Create help document structure */
137 ChDocument* chCreateDocument (const char* name, const char* title);
138 
139 /* Destroy help document structure */
140 void chDestroyDocument (ChDocument* pDoc);
141 
142 /* Add section to the document */
143 ChSection* chAddSectionEntry (ChDocument* pExDoc,
144  const char* label, const char* title);
145 
146 /* Add some text to the section */
147 void chAddSectionText (ChSection* pSection, const char* text);
148 
149 /* Add reference to the section */
150 void chAddSectionRef (ChSection* pSection, ChRefKind kind,
151  const char* link, const char* title);
152 
153 
154 /***********************************************************************
155  * Query help
156  ***********************************************************************/
157 
158 /* Find the section by name */
159 ChSection* chQuerySection (ChDocument* pDoc, const char* label);
160 
161 /* Get first defined section */
162 ChSection* chStartSection (ChDocument* pDoc);
163 
164 /* Get next section */
165 ChSection* chNextSection (ChSection* pSection);
166 
167 
168 /***********************************************************************
169  * Table of contents
170  ***********************************************************************/
171 
172 /* Create table of contents */
173 ChReference* chCreateTableOfContents (ChDocument* pDoc);
174 
175 /* Destroy table of contents */
176 void chDestroyTableOfContents (ChReference* pTOC);
177 
178 
179 #ifdef __cplusplus
180 };
181 #endif /* __cplusplus */
182 
183 #endif /* helpdoc.h */
ChReadDocEnv
Definition: helpdoc.h:90
ChRefTag
Definition: helpdoc.h:54
ChDocument
Definition: helpdoc.h:75
ChSectTag
Definition: helpdoc.h:64
Generated by   doxygen 1.8.5