:: Re: [DNG] Documentation format phil…
Pàgina inicial
Delete this message
Reply to this message
Autor: Steve Litt
Data:  
A: dng
Assumpte: Re: [DNG] Documentation format philosophies
On Sat, 11 Nov 2017 12:15:44 +0000
jack da <picamanic@???> wrote:

> Steve Litt: these days I write all my personal documents with
> Leafpad, which adds word-wrap capability to what can be achieved with
> plain text editors ex, nano, etc.


If you include Vim in that list, Vim has at least one Zencoding plugin.
With Zencoding, you can set up a start/end tag pair, with the cursor
resting where you're supposed to type, with one keystroke.
>
> I discovered that I cannot access the raw MarkDown text of the
> original Alternative Init .. document [copy+paste from the
> talk.devuan.org web site strips the markup directives]. Just as well
> I will write the new paper from scratch.


Markdown, Asciidoc, and Asciidoctor are wonderful *for what they do*.
They're not a documentation be all and end all.

>
> I was once fluent in HTML, and XHTML seems to just to be a strict
> version thereof.


Yes. And as far as fluency, when you use Bluefish, it makes
suggestions for what tags to put and what to put in the tags, making
Xhtml open to the less than fluent.



> We use LaTEX in technical documents,


LaTeX is wonderful *for what it does*, which is make beautifully
typeset documents whose linefeeds are determined at compile time, not
at read time (like ePub, HTML or Xhtml). The problem is that you can't
reasonably convert LaTeX to XML, HTML, Xhtml or the like.

LaTeX is the best around if you know the page size, line width, and
margins at compile time.

> and I can
> quickly become fluent in any sensible markup language [including
> MarkDown].


Yes. Markdown and Asciidoc are dead bang simple.

>
> The question to ask is: are the documentation tools widely
> available; are they open source; can they be built without many
> dependent packages/libraries?



Let me answer your questions, in the context of the Bluefish editor,
which I think is superior for HTML, Xhtml, and probably several other
languages:

* Widely available? : Yes. Most distros have a Bluefish package, and
you can compile the code straight from the Bluefish authors. I had to
do this when the Void Linux version of Bluefish went bad.

* Open Source? : Yes. GNU General Public License, version 3, or at
your option, later.

* Few dependent packaes/libraries? : No. Bluefish has lots of
dependencies. It's a GUI program useful in many human languages,
capable of understanding many computer languages. Its realtime
semi-authoring of code makes it both a huge timesaver and a program
with serious dependencies. The following is a list of its direct
dependencies:

===========================================
[slitt@mydesk ~]$ xbps-query -x bluefish
hicolor-icon-theme>=0
desktop-file-utils>=0
xmlcatmgr>=0
python>=0
glibc>=2.8_1
gtk+3>=3.0.0_1
pango>=1.24.0_1
cairo>=1.8.6_1
gdk-pixbuf>=2.22.0_1
glib>=2.18.0_1
libxml2>=2.7.0_1
enchant>=1.4.2_1
gucharmap>=3.0.0_1
[slitt@mydesk ~]$
============================================

Unless you've managed to live without GTk all these years, none of
these direct dependencies look particularly harmful to me. As far as I
can tell, no KDE libs, no Gnome libs, no systemd.

My advice would be to try Bluefish for a couple weeks, then decide
whether to keep it or throw it away and uninstall all auto-installed
packages no longer necessary.

SteveT

Steve Litt
October 2017 featured book: Rapid Learning for the 21st Century
http://www.troubleshooters.com/rl21