discuss: Review: Vim as XML Editor HOWTO
Subject:
Re: Review: Vim as XML Editor HOWTO
From:
Saqib Ali ####@####.####
Date:
3 Jan 2004 19:50:25 -0000
Message-Id: <Pine.GSO.4.55.0401031122410.7841@sjgcs1.stsj.seagate.com>
Hello,
I went through the document. And seems to contain lot of useful
information. I like the scripts contained in the document. I think the
document will be a valuable addition to the TLDP datbase.
However I also think that the document is NOT very well organized, and is
lacking explanation/details in certain sections of the document. A VI guru
might be able to follow the document, but a newbie, like me, may not be
able to do so.
Maybe someone from the TLDP mailing list would like to propose a detailed
outline of how this particular document should flow, to make it easier for
the user to read.
Saqib Ali
-------------
http://validate.sf.net <---- DocBook XML -> HTML Convertor
On Sat, 3 Jan 2004, Emma Jane Hogbin wrote:
> Hi Tobias,
>
> I notice that your Vim as XML Editor has been proposed to the LDP and is
> waiting for a review. I am currently a technical reviewer for the LDP and
> offer these solicited comments. Please note that I have CC-d this email
> to the discuss mailing list and the Review Coordinator (Tabatha Marshall).
> If you are not currently subscribed to the discuss list you can read any
> follow-up email at: http://lists.tldp.org/ (click the mailing list email
> to read the archives).
>
> Review: Vim as XML Editor HOWTO
> Reviewer: Emma Jane Hogbin
> Type of review: overall structure (peer review)
> Review guidelines: http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/peerreview.html
> Document URL: http://www.pinkjuice.com/howto/vimxml/index.xml
> Document Author: Tobias Reif
>
> The result of this report is being reported according to:
> http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/reporting.html
> No changes have been made to the original document.
>
> ------------------------------------------------------------------------
> --------------- Review of Vim as XML Editor HOWTO ----------------------
> ------------------------------------------------------------------------
> 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.
>
> Overall I found your document difficult to follow and would not accept it to
> the LDP as is.
>
> 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. If a specific
> script has pre-requisite installs, move installation information of the
> language to an Appendix. For example: Jing requires Ruby. 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. I recommend moving
> all Ruby information to an Appendix.
>
> - 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. 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
>
> - 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. The second problem is
> that I don't know how why it doesn't work. The third problem is that it's
> not legible 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."
>
> - Sort information by topic. For example: the xmllint script can validate
> DocBook documents. Create a heading for "Validation" and add all related
> scripts to this section. You also have scripts which I feel fit under
> the following headings: Markup and Tag Helpers (matchit, xmledit),
> Document Statistics (xmlstar), "Clean" Documents (Tidy, xmlstar, xmllint)
> Your current topics require a user to read the entire document start to
> finish to find information which is relevant to their needs. As a user
> I would rather be able to find information on "validation" than
> information on "setup" ... especially considering I setup a number of
> things from your HOWTO only to realize later that they were not useful
> to me.
>
> - 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. You tell me that it calls
> saxon...but I don't know what it /does/. The section heading, "More
> Setup" does not give me any clues either. You refer to pretty-printing.
> And later you use pretty-printing to describe the tags in a DocBook
> document, but you start the pretty print section by talking about why
> xmllint doesn't work so I have no idea that xsltlint is going to be
> included in the section. The setup information and the usage information
> should be cross-referenced. 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).
>
> - To allow users to jump easily to any point in the document I would
> include a setup section which lists all programs alphabetically. Users
> would then be able to easily find install information for any script
> in the document. I would also separate this list into information
> for Windows vs. Linux users. For example:
> Linux
> - xmllint
> - install information
> - configuration information
> - sample uses
> - Jing
> - requires ruby
> - install information
> - configuration information
> - sample uses
> Or I would provide the information by script with operating system
> information as a sub-section.
> - xmllint
> - install information: Windows | Linux
> - configuration information: Windows | Linux
> - sample uses
> - Jing
> - only available to Linux users
> - install information
> - configuration information
> - sample uses
>
>
>
>
> --
> Emma Jane Hogbin
> [[ 416 417 2868 ][ www.xtrinsic.com ]]
>
> ______________________
> http://lists.tldp.org/
>
>
