Subject:
Re: Review: Vim as XML Editor HOWTO
From:
Tobias Reif ####@####.####
Date:
31 Jan 2004 22:12:56 -0000
Message-Id: <20040131221457.GA5837@linux>
Hi Emma
Thank you very much for your feedback.
On Sat 2004-01-03 Emma Jane Hogbin wrote:
[...]
> I notice that your Vim as XML Editor has been proposed to the LDP
> and is waiting for a review.
I don't know the TLDP's process but the page
http://www.tldp.org/authors/inprogress.html
is called "In Progress" and the note regarding my howto labels it as
draft (as does the front page of the howto, which also labels it
version 0.*).
So it's not the case that I submitted a howto that I view as finished
(eg 1.*); and I also didn't ask for inclusion:
http://lists.tldp.org/index.cgi?5:mss:5466
:
"This
http://www.pinkjuice.com/howto/vimxml/
is still a draft.
The sources are here:
http://www.pinkjuice.com/howto/vimxml/docbook/ .
Since that's where the latest version is located it doesn't make much
sense to copy the files to your CVS repository, I think.
I just wanted to ask if you would like to link the howto as soon as
it's finished."
Then I submitted the link (not the sources) for inclusion in
http://tldp.org/authors/inprogress.html
:
http://lists.tldp.org/index.cgi?7:mss:3401
:
'P.S.
Sorry, I just found
http://tldp.org/authors/inprogress.html
"If you are working on a new HOWTO, FAQ, or Guide; or have an idea/topic
for a new document please inform the LDP so that the document can be
added to this list."
document:
Vim as XML Editor
type:
HOWTO
author(s):
Tobias Reif
tobiasreif(at)pinkjuice.com
notes:
draft
[http://www.pinkjuice.com/howto/vimxml/]
is available.
'
But as I say in my howto, I appreciate any feedback.
> [...]
> I currently use Vim to edit all of my DocBook, XHTML and PHP
> documents. I would not consider myself a "power user", however, I do
> consider myself to be a competent user. I learned about a number of
> scripts from your document. Some have shown to be quite useful to
> me, such as matchit.vim. Others have I have not used at all even
> though they are now on my machine, such as Jing.
I'm not sure if I understand the problem or if there is one.
moresetup.xml#jing lists Jing's home page which states that Jing is a
Relax NG validator. If you don't need an RNG validator then you don't
need to install Jing. (... and if you don't want to install things you
don't need then you shouldn't install it)
But I'll change
"The normative schemas of many XML standards will be written in RNG,
and Jing is written by one of the main creators of RNG, James Clark."
to
"The normative schemas of many XML standards will be written in RNG,
and Jing is [[added:] an RNG validator] written by one of the main
creators of RNG, James Clark."
> Overall I found your document difficult to follow
There definitely is room for improvement, I agree. It's more a
collection of tips than a complete instructional guide intended to be
read from cover to back. (I'll add this info to the intro)
Perhaps I'll add something like this:
'This howto is an organically growing collection of illustrative
examples and tips which might inspire some readers to create their own
personal XML editing environment and develop their own workflows, not
a finished one-size-fits-all walkthrough or "complete" cookbook where
each reader is supposed to end up with the same prescribed
environment.'
> and would not accept it to the LDP as is.
This verdict can't be surprising to anyone since the document is
still a draft.
In
http://lists.tldp.org/index.cgi?1:mss:5331:200311:ikndjmbepldekebhjjej
you wrote
"Because I have spent literally hundreds of hours writing
documentation for open source projects. And I know that as soon as I
write a document it has the potential to be: (1) out of date the next
day; (2) never acknowledged by the software development team. I'd like
to think I write good documentation, but it is a LOT of work and even
after a LOT of work it's never perfect. So if it's hard enough for me
to write good documentation, I certainly don't expect perfect
documents from other people. I expect something that has a tidbit of
useful information which Google knows how to find, everything else is
icing on the cake."
I also spent *lots* of hours writing this howto, and the todo list
still is long.
It's still a draft, and I didn't yet ask for inclusion, but I get "I
[...] would not accept it [your document] to the LDP as is." I
didn't ask you if you would accept the document, but I get the above
harsh answer to a question I didn't pose: I feel being attacked for no
reason.
If you want authors who work hundreds of hours without getting paid to
offer their work you might want to avoid alienating them.
No one continues to work for free on a document if the activity is not
fun anymore.
I do appreciate the reasoned parts of your review, and I appreciate
your interest in my document and the time you spent reviewing it. I
hope I'll find the time to improve it further.
Tille wrote in the "DVD Playback HOWTO draft" thread:
"if you want I'll do the technical review. when you feel ready for
it."
That's a good workflow IMHO.
Nevertheless I'll try to understand all your criticism and all your
suggestions, but we might have to agree to disagree on some points
(your / the TLDP's idea of how a howto should be might differ from
mine, which would be OK for me).
Currently I want to leave the document where it is:
license.xml:
"As long I'm maintaining the document I won't publish copies elsewhere
on the web and I don't encourage you to do so either. It's hard to
keep multiple copies up to date and people will be confused by finding
potentially different versions at multiple locations when searching
the web. At some point I might offer the document to tldp.org/ and
move it there if they accept it."
So at some point I might offer the howto for inclusion in the TLDP,
but currently this is not a goal.
Perhaps the entry on the "In Progress" page should be deleted?
> My recommendations are as follows, I hope you find them useful.
>
> - Improve the flow of the document. Currently your table of contents
> includes the following main sections:
> About
> Setup
> More Setup
> Tasks
> More Tasks
> Combine the "More" sections into the previous sections.
That's what I had before. The chapters "Setup" and "Tasks" got too
long (long download on slow connections, very long pages to scroll),
so I split each of them in two. This decision certainly has it's
problems, but at least for the setup sections it fits well: the
sections in chapter "More Setup" are not as basic and crucial as the
sections in the preceding chapter, and discuss more or less optional
components. I'll add this info to the chapter.
The division also fits the other pair of chapters: The task
descriptions in chapter Tasks mostly deal with creating XML, and the
task descriptions in More Tasks deal with created or existing XML.
> If a specific script has pre-requisite installs, move installation
> information of the language to an Appendix.
Personally I don't think this would be a good thing. Installation
instructions are content thus belong in a chapter not in an appendix,
IMHO.
> For example: Jing requires Ruby.
Jing requires Java, jing requires Ruby :)
moresetup.xml#jing
:
"Jing doesn't (yet) support stdin so I use a simple Ruby script to
fake it for now.
Make sure you have the required version of the JRE. I recommend the
latest version, currently that's 1.4.
java -version"
> If a user already has Ruby installed, or does not want to use Jing
> they should be able to easily skip the section on installing Ruby.
This user can already skip it if he already has Ruby installed:
moresetup.xml#ruby :
"Make sure that you have the latest version or 1.8
$ ruby -v
otherwise install it."
"Some scripts in this howto are written in Ruby so I recommend to
install it."
The user sure is free to check if he will setup and use any scripts
that use Ruby, or postpone the installation until he needs it.
Intro:
"This is just a howto. I will simply show my current setup; there are
many different variations possible."
I can not know which prerequisites will be required for a specific
requirements profile of a specific user.
> I recommend moving all Ruby information to an Appendix.
See above.
> - Any script, file, or example longer than 25 (or so) lines seriously
> compromises the readability of a document. I would recommend removing
> long scripts and setups to the end of the document as an Appendix, or
> make the files available as a separate download.
The target audience is coders, and coders generally enjoy reading
code :)
My (very long) todo list includes making all scripts available as one
archive file.
> For example, your .vimrc file. In the text of your document you
> should include specific information about what you have in your
> setup file. The example right after the .vimrc file which
> describes map leader is good and should stay in the main document.
> The rest of the information from your .vimrc file is either
> covered elsewhere in your document, or should be explained in
> detail (not just copied and pasted without context or explanation)
> See: http://www.pinkjuice.com/howto/vimxml/setup.xml
The howto is a draft, I plan on explaining more parts of the vimrc.
> - Clearly explain Vim shortcuts. For example in the section on Marking Up
> Tables I cannot follow this example:
> [mapleader] x g g > G : % s / $ / [space] . / [enter] g g O
> [ctrl-d] < t a b l e > > [esc] d d . G p 2 G
> http://www.pinkjuice.com/howto/vimxml/tasks.xml#markinguptables
> The first problem is that it doesn't work for me.
Please elaborate, otherwise I have no chance of finding out what went
wrong or what to fix and how.
> The second problem is that I don't know how why it doesn't work.
If you don't tell me what happens when you try it then I also can't
know why it doesn't work.
At the beginning of that chapter it says:
"Most of the examples and instructions will only work as shown when
carried out in an environment set up as described in the previous
chapters."
That might be a factor.
> The third problem is that it's not legible
Can you explain why not? There's a list of characters that are to be
input.
about.xml#conventions says
:
"Notation
Key sequences to be entered in Vim are written like this: 2 G [ctrl-v]
[down] x. All commands are to be entered in normal mode. Insert mode
commands start with an i, command line ones start with a :. Longer
commands that are to be entered in Vim's command line are written like
this:
:'<,'>s/<span\_s\+class="bold">\(\_.\{-}\)<\/span>/<em>\1<\/em>/g
In key sequences like this one [mapleader] x i < c h a p t e r > >
[up] each group of non-space characters stands for one key press. If a
space is to be entered it is listed as [space].
[...]
I don't use the notation used in Vim scripts because I think it's not
very descriptive. If you want to use some of the commands in your Vim
scripts, you must translate the function keys, eg [enter] to <CR> and
[backspace] to <BS>."
> so I am unable to extract useful information from it to try
> and figure out why it doesn't work. The following information needs to
> be added to sections with examples such as this one:
> - scripts required including which key letters/keys
> are used in your sample. For example: [mapleader] x
> calls the *** script.
> Note: You provide some of the information in "Marking Up Text."
I could add more such explanations, but stuff like gg is too basic
(beginners are addressed in about.xml#learningvim), and stuff like
< t a b l e > >
has been explained/demonstrated in a previous section
(tasks.xml#creatingtags).
> - Sort information by topic. For example: the xmllint script can validate
> DocBook documents.
It can be used for validating any XML document, and can be used for
many more tasks, just like many other tools can be used for different
types of tasks; there are overlaps as well.
> Create a heading for "Validation" and add all related scripts to
> this section.
xmllint can also be used for pretty-printing, entity reference
expansion, XInclude resolving, etc. Facts like this complicate the
suggested hierarchical categorisation.
Adding one more level of nesting will also decrease usability and
accessibility (at least for me) by making navigation harder.
I have now:
top level:
chapters (pages in the online version): Setup, Tasks, etc
second level:
sections (page TOC entries): xmllint, Creating Tags, etc
third level:
sub sections: On Windows, On Linux, etc
Adding one more level will make navigating the online version more
difficult for many; I'm a big fan of structuralizing information, but
for the sake of usability and accessibility I won't nest sections
deeper than one level.
A deeper nesting is also hard to represent in the print version, IMHO.
> [... snipped: more regarding the above ...]
> Your current topics require a user to read the entire document
> start to finish to find information which is relevant to their
> needs.
I don't agree.
(And on each page there is a page TOC allowing the reader to quickly
browse the sections.)
> As a user I would rather be able to find information on
> "validation" than information on "setup" ...
I thought about this a while ago and decided against it.
(BTW, there is a section named "Validation")
If I would change the toplevel structure from
Tasks,Setup,...
to the more obvious
Validation,Pretty-Printing,...
then this would bring relevant problems:
* The chapter count would be increased by something like ten.
Searching through the howto (eg with ctrl-f) would become much
harder (currently there are just four core content chapters).
I don't want to upload a redundant one-file version, but instead
keep the toplevel element/page/chapter count low.
* Many tools are required for several different types of tasks.
If I have Validation and Pretty-Printing as chapters, then there
would be no obvious location to put (or expect) the installation
instructions for xmllint.
These issues could be dealt with, but in general each of the different
sensible structuralizations has it's pros and cons.
If we would mark up the information rich enough we could generate
different "views", each based on a different structure. But since the
display formats are static and since we want to keep it simple we have
to decide on one structure, although it has it's cons.
> especially considering I setup a number of things from your HOWTO
> only to realize later that they were not useful to me.
I see the problem. On the other hand this should not happen as I do
explain what each tool or script is used for:
setup.xml#matchitvim
"Jump around the buffer with %, eg between opening and closing angle
brackets of XML tags and between opening and closing tags when XML
syntax recognition is turned on."
setup.xml#xmledit
"Devin Weaver's xmledit provides some editing features such as closing
and deleting tags, and wrapping strings in tag pairs."
setup.xml#catalogs
"When validating an XML document which references an online DTD in
it's doctype declaration,
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
this DTD needs to get loaded. Normally it gets downloaded from the
web, which can take a while with large schemas such as DocBook.
Changing the URL to a local path each time is tedious, especially if
there are many documents.
Convenient and fast offline validation can be achieved though setting
up a catalog system. When using xmllint, this means nothing more than
creating a simple catalog file, and making its path available to
xmllint."
setup.xml#xmllint
"xmllint is part of libxml, the XML C library for GNOME. It's
lightning fast and can be used for validation and pretty printing."
Those short summaries should allow the reader to decide if he needs
the respective tool or script. (Being familiar with XML technologies
and having various XML editing needs and knowing about them is a
requirement.)
I could name the chapters "Validation, Pretty-printing, ...", but going
with "Setup, Tasks" has more advantages IMHO:
* Many tasks require the same tools, grouping their setup instructions
makes sense. Above you suggested to move setup instructions to the
end of the document as an appendix; I agree that grouping them is a
good idea, but leave them as content in the core content chapters.
* Many tools fit into more than one category.
* Setting up tools and learning about possible ways for completing
specific tasks are different types of activities; reflecting this in
the howto's structure is one way that I found and find sensible.
I could switch to the structure you suggest, but just as the one I
currently use it would have severals pros and cons.
> - Clearly explain which are your scripts and what their benefits
> are. For example: xsltlint.rb as described on
> http://www.pinkjuice.com/howto/vimxml/moresetup.xml
> I have no idea what this script actually does.
It pretty-prints, as noted at the beginning of this section.
> You tell me that it calls saxon...
I tell you much more, see the howto.
> but I don't know what it /does/.
moresetup.xml#xsltlint
:
"Sometimes it's handy to have a pretty-printer which supports XSLT 2.
^^^^^^^^^^^^^^
XSLT 2 has many features which are generally useful and it supports
serialization to "HTML compatible" XHTML 1. I wrote a simple Ruby
script calling Saxon 7, but that's just an example; you could use any
other language and any XSLT processor which supports XSLT 2."
> The section heading, "More Setup" does not give me any clues
> either.
It doesn't have to, the info is right there in the section AFAICS.
> You refer to pretty-printing.
Yes, that's what it does.
> And later you use pretty-printing to describe the tags in a DocBook
> document,
I don't know what you're referring to here.
> but you start the pretty print section by talking about why
> xmllint doesn't work
That's not true, unless I misunderstand you. The pretty-print section
moretasks.xml#prettyprinting
starts with
:
"Pretty-printing is not a trivial task. Relevant details of your
document might be changed, so beware. I mainly use pretty-printing
when viewing documents with extremely long lines or no indention, or
when editing XML generated by tools, but I nearly never use a
pretty-printing tool to format the code of documents I author."
Then I show how to use xmllint's pretty-printer, which works in most
cases, is fast, and is present on many distros.
Then, I show a scenario where it doesn't fully suffice, and give a
solution (slower, less commonly available). There are many more
alternatives to xmllint for pretty-printing, that's not a problem
IMHO.
> so I have no idea that xsltlint is going to be included in the
> section.
I don't see why you should; when I read a camera howto section
explaining how to get pictures from my camera then I don't know in
advance which tools it will feature, that's not a problem for me,
generally.
> The setup information and the usage information should be
> cross-referenced.
Very good idea. But the XSLTs which generate the XHTML form the DBX
sources (see about.xml#colophon) don't yet support xrefs.
> This would allow me to click from setup to usage and see if the
> script is useful to me (and therefore is something I should
> install).
But there already is information provided which should allow the
reader to make this decision. Either you need to pretty-print
fragments/buffers/files/documents or not; it's up to the reader, the
howto (respectively I) can't know.
But cross-references from setup sections to task sections would be
useful, I agree.
> - To allow users to jump easily to any point in the document I would
> include a setup section which lists all programs alphabetically.
Note that the print version features an alphabetical index, and that
since the source contains indexing markup an index could also be
generated for the online version (my DocBook to XHTML XSLTs don't
support this yet).
> Users would then be able to easily find install information for any
> script in the document.
Interesting idea. On the other hand there are only two setup pages,
and there are page TOCs and the browsers search functions such as
ctrl-f which can be considered faster than loading and reading a
separate index page.
By the way, I also would appreciate bug reports regarding any code in
the howto, and reports on typos. And encouraging statements regarding
positive aspects are welcome as well :)
Thanks again for taking the time to review my howto,
Tobi
--
Vim users, don't forget to
http://iccf-holland.org/donate.html
