Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
documentation_notes [2007-06-09 11:31] – external edit 127.0.0.1documentation_notes [2014-02-28 01:41] (current) – [documents that are in PDF format] nik
Line 1: Line 1:
 +===== notes on documentation, processes, tools + ephemera =====
  
 +===== formats + software =====
 +[[File Formats]]  /  [[Open Codecs]] / [[AntiWord]]
  
-===== notes on documentation, processes, tools + ephemera ===== +==== documents that are in PDF format==== 
 +using Skim to annotate pdfs on MacOS > http://skim-app.sourceforge.net/
  
-==== formats + software ==== +merging two pdfs ''skimpdf merge IN_PDF_FILE_1 IN_PDF_FILE_2 [OUT_PDF_FILE]''
-[[File Formats]]  //  [[Open Codecs]] //  [[AntiWord]]+
  
 +to merge annotations/notes from 2 pdfs;
 +  - open doc-1.pdf in Skim  
 +  - export note from "File > Export" with "Skim Notes" format
 +  - open doc-2.pdf in Skim
 +  - import notes via "File > Read Notes" make sure to unselect "replace existing notes"
 +  - save doc-2.pdf
  
-=== docs using  LaTeX ===+==== documents that uses LaTeX ====
  
  
-"The original documentation source is [[LaTeX]]. Simply running LaTeX gives you DVI, which you can convert into publication quality Postscript. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML." +"The original documentation source is [[LaTeX|LaTeX]]. Simply running $\LaTeX$ gives you DVI, which you can convert into publication quality Postscript. Using ''pdflatex'' (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using ''latex2html'', you can create almost native-quality HTML documentation. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML." 
  
 "latex2html comes with LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions." "latex2html comes with LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions."
Line 27: Line 35:
   * It's available for minimal money and effort.   * It's available for minimal money and effort.
   * It's highly extensible. If you need to do something that doesn't come as standard, you almost certainly can (and someone else almost certainly already has, and put it on CTAN for you).   * It's highly extensible. If you need to do something that doesn't come as standard, you almost certainly can (and someone else almost certainly already has, and put it on CTAN for you).
-  * [[LaTeX]] versions are not incompatible. The file format has never changed. I have LaTeX files from 1989 that work without problem in the latest version of LaTeX.+  * [[LaTeX]] versions are not incompatible. The file format has never changed. I have $\LaTeX$ files from 1989 that work without problem in the latest version of $\LaTeX$.
  
-The only downside I can think of is the learning curve. Basic LaTeX use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.+The only downside I can think of is the learning curve. Basic $\LaTeX$ use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.
 ---- ----
  
  
  
-=== XML, XSLT and Docbook ===+==== XML, XSLT and Docbook ====
  
 I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in. I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in.

User Tools

Page Tools

Site Tools