res/builder/build-srcpkg/shlib/doc/readme.txt

   1
   2 @ gendocs.sh
   3 # gendocs.sh --email bug-texinfo@gnu.org -o <output-file-name> <tex-file-name> "GNU Texinfo manual"
   4 # gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
   5 # info, text, html, dvi, pdf,
   6
   7
   8
   9
  10
  11
  12 # doc type
  13 ----------
  14
  15 * txt
  16 * *md
  17 * *rst
  18 * tex
  19 * docbook
  20
  21 * man
  22 * info
  23 * dvi
  24 * *ps
  25 * pdf
  26 * html
  27 * chm
  28
  29     tex & docbook are src doc file, they are used to generate other docs.
  30         generally, txt/tex/dvi/pdf/html is used for GNU standard doc, and man/info
  31 are the standard cmd helper file.
  32     md file is nearly equal to txt file, but it append light weight punct
  33 signature, to seperate doc in text, and to display good appearence in html.
  34
  35     for a srcpkg, there are different kinds of doc:
  36
  37 * helper file
  38 * menual file
  39 * apidoc file
  40 * online src
  41 * website pages
  42
  43     man & info is the default helper file for cmd. it generated by tex file.
  44         dvi/ps/pdf/html are usually used for manual doc. but some srcpkg uses md or
  45 rst file, it can be viewed directly, and also can be generated to html file for
  46 good appearence.
  47     apidoc is generated by src code, normally, we uses doxygen.
  48         online src is generated by src code, normally, we uses pmccabe and others.
  49     gendocs.sh in gnutils/aux generate html website pages.
  50
  51
  52 # texi to others
  53 ----------------
  54
  55 * texi2info
  56 * texi2dvi
  57 * texi2pdf
  58 * texi2txt
  59 * texi2html
  60 * texi2html in split charpter
  61
  62 : ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="}
  63 : ${MAKEINFO="makeinfo"}
  64 : ${TEXI2DVI="texi2dvi"}
  65 : ${DOCBOOK2HTML="docbook2html"}
  66 : ${DOCBOOK2PDF="docbook2pdf"}
  67 : ${DOCBOOK2TXT="docbook2txt"}
  68 : ${GENDOCS_TEMPLATE_DIR="."}
  69 : ${PERL='perl'}
  70 : ${TEXI2HTML="texi2html"}
  71
  72
  73 ## texi2info
  74 ------------
  75
  76 cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\""
  77 echo "Generating info... ($cmd)"
  78 rm -f $PACKAGE.info* # get rid of any strays
  79 eval "$cmd"
  80
  81
  82 ## texi2dvi
  83 -----------
  84
  85 cmd="$SETLANG $TEXI2DVI $dirargs $texarg \"$srcfile\""
  86 printf "\nGenerating dvi... ($cmd)\n"
  87 eval "$cmd"
  88
  89
  90 ## texi2pdf
  91 -----------
  92 cmd="$SETLANG $TEXI2DVI --pdf $dirargs $texarg \"$srcfile\""
  93 printf "\nGenerating pdf... ($cmd)\n"
  94 eval "$cmd"
  95
  96
  97 ## texi2txt
  98 -----------
  99 opt="-o $PACKAGE.txt --no-split --no-headers $commonarg"
 100 cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
 101 printf "\nGenerating ascii... ($cmd)\n"
 102 eval "$cmd"
 103
 104
 105 ## texi2html
 106 ------------
 107
 108 opt="--split=$1 --node-files $commonarg $htmlarg"
 109 cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\""
 110 printf "\nGenerating html by $1... ($cmd)\n"
 111 eval "$cmd"
 112
 113 # texi2html by makeinfo
 114 opt="--no-split --html -o $PACKAGE.html $commonarg $htmlarg"
 115 cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
 116 printf "\nGenerating monolithic html... ($cmd)\n"
 117 rm -rf $PACKAGE.html  # in case a directory is left over
 118 eval "$cmd"
 119
 120
 121 ## texi2html in split charpter
 122 ------------------------------
 123
 124 # split texi2html
 125 opt="--html -o $PACKAGE.html $split_arg $commonarg $htmlarg"
 126 cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
 127 printf "\nGenerating html by $split... ($cmd)\n"
 128 eval "$cmd"
 129
 130 # use texi2html
 131 opt="--output $PACKAGE.html $commonarg $htmlarg"
 132 cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\""
 133 printf "\nGenerating monolithic html with texi2html... ($cmd)\n"
 134 rm -rf $PACKAGE.html  # in case a directory is left over
 135 eval "$cmd"
 136
 137   html_split node
 138   html_split chapter
 139   html_split section
 140
 141
 142
 143
 144
 145
 146
 147
 148 # docbook to others
 149 -------------------
 150
 151 * texi2docbook
 152 * docbook2html
 153 * docbook2txt
 154 * docbook2pdf
 155
 156
 157 ## texi2docbook
 158 ---------------
 159
 160 opt="-o - --docbook $commonarg"
 161 cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml"
 162 printf "\nGenerating docbook XML... ($cmd)\n"
 163 eval "$cmd"
 164
 165
 166 ## docbook2html
 167 ---------------
 168
 169 opt="$commonarg -o $split_html_db_dir"
 170 cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\""
 171 printf "\nGenerating docbook HTML... ($cmd)\n"
 172 eval "$cmd"
 173
 174
 175 ## docbook2txt
 176 --------------
 177
 178 cmd="$DOCBOOK2TXT \"${outdir}/$PACKAGE-db.xml\""
 179 printf "\nGenerating docbook ASCII... ($cmd)\n"
 180 eval "$cmd"
 181
 182
 183 ## docbook2pdf
 184 --------------
 185
 186 cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\""
 187 printf "\nGenerating docbook PDF... ($cmd)\n"
 188 eval "$cmd"
 189
 190 #
 191
 192
 193 # others
 194 --------
 195
 196 ## man2info
 197 -----------
 198
 199 ## info2html
 200 ------------
 201
 202 ## md2html
 203 ----------
 204
 205
 206 ## rst2html
 207 -----------
 208
 209
 210 ## html
 211 -------
 212
 213
 214 ## pdf
 215 ------
 216
 217
 218 ## tex
 219
 220
 221 ## man
 222 ------
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262 @ docgen
 263 # txt
 264 + md ==> html£¬discount
 265 + rst ==> html£¬
 266 # html
 267 + html ==> chm£¬htmldoc/chmcmd/htmldoc2chm
 268 + html ==> pdf£¬wkhtmltopdf/htmldoc
 269 + man ==> html£¬man2www
 270 man -t --html=/usr/bin/firefox diff
 271 firefox /tmp/hmanLSa2jh/diff.html
 272 + info ==> html£¬info2www
 273 # pdf
 274 + txt
 275 + tex
 276 pdflatex example1.tex
 277 »òtex ==> dvi ==> pdf
 278 + man
 279 man ¨Ct diff |ps2pdf ¨C diff_man.pdf
 280 + dvi
 281 dvipdfm[x] example1.dvi # =>£» °Ñexample1.dvi ×ªÎªexample1.pdf
 282 + ps
 283 ps2pdf example1.ps =>£» ÓÃexample1.ps Éú³Éexample1.pdf
 284 + html£¬
 285 # tex
 286 + tex ==> dvi£¬texi2dvi/texi2any
 287 latex example1.tex # ==> example1.dvi
 288 + tex ==> man£¬
 289 makeinfo xxx.tex
 290 + tex ==> info
 291 + tex ==> pdf
 292 + tex ==> html£¬texi2html/texi2any
 293 # docbook
 294 + docbook ==> txt
 295 + docbook ==> dvi
 296 + docbook ==> man
 297 + docbook ==> info
 298 + docbook ==> pdf
 299 + docbook ==> html
 300 # dvi ==> ps
 301 dvips -ppdf example1.dvi # =>£» Éú³Éexample1.ps
 302
 303 @ man
 304 # man ==> txt
 305 man ¨Ct diff |col ¨Cb > diff_man.txt
 306 # man ==> pdf
 307 man ¨Ct diff |ps2pdf ¨C diff_man.pdf
 308 # man ==> html
 309 man -t --html=/usr/bin/firefox diff
 310 firefox /tmp/hmanLSa2jh/diff.html
 311
 312
 313
 314
 315 1¡¢ÈçºÎÓÃCtex»òÕßLatexÊä³öPDF¸ñÊ½µÄÎÄ¼þ ¿ÉÒÔµÄ£¬³ýÁËÊä³öPDF¸ñÊ½»¹Ö§³ÖÉú³ÉpsÎÄ¼þ
 316
 317 % example1.tex
 318
 319 documentclass{report}
 320 begin{document}
 321 This is my first {atex} typesetting example.
 322 this is my first atex{} typesetting example.
 323 this is my first atex typesetting example.
 324 i am mr. edward g.j. lee, g.j. is a abbreviation of my name.
 325 i am mr. edward g.j. lee, g.j. is a abbreviation of my name.
 326 please see appendix a. we will be there soon.
 327 please see appendix a
 328 ull. we will be there soon.
 329 nd{document}
 330
 331 ±ÈÈçÒÔÉÏÕâ¸ötexÎÄµµ£¬¿ÉÒÔÕâÑù±àÒëÉú³Épdf:
 332
 333 1.Ö±½ÓÉú³Épdf
 334
 335 pdflatex example1.tex
 336
 337 2.ÓÃdviÎÄ¼þÉú³ÉÉú³Épdf
 338
 339 latex example1.tex =>£» Éú³Éexample1.dvi
 340 dvipdf example1.dvi =>£» °Ñexample1.dvi ×ªÎªexample1.pdf
 341
 342 3.ÓÃpsÎÄ¼þÉú³Épdf
 343
 344 latex example1.tex =>£» Éú³Éexample1.dvi
 345 dvips -ppdf example1.dvi =>£» Éú³Éexample1.ps
 346 ps2pdf example1.ps =>£» ÓÃexample1.ps Éú³Éexample1.pdf