discuss: Thread: One-page replacement for LDP-Author-Guide (not exactly, but ...)

I've just rapidly written a one-page replacement for the
LDP-Author-Guide.  The Guide is far too long and is intimidating for
most people that are thinking of writing a HOWTO, etc.  It may take
longer to read the Guide and digest it than to write a short HOWTO.

My one-pager is not exactly a replacement since it points to the Guide if
the reader wants to use DocBook.  If the choice is LinuxDoc it point to
my Howtos-with-LinuxDoc mini.  If this one-pager is accepted, then I'll
revise the mini so that infomation which duplicates info in the
one-pager can be skipped over.

My one-pager is based on Tim Bynum's work which was based (to some
extent) on previous stuff.  But I'm sure he won't mind my using it
without credit (it's mostly my stuff anyway).  A link to this one-pager
would be in the Author / Contribute section of our main webpage.  Or it
could be in Contribute/ Help (or better yet, in both).  Perhaps
"Contribute / Help" could be renamed "Volunteers Wanted".  A  plug for
helping with reviews should be in here somewhere.

			David Lawyer
PS:
Here's my one-pager.  I know that my date format conflicts with the
Guide but I think it's better.  Note this is only a first draft, but I
strongy feel that something short like this is needed that will also
offer the option of LinuxDoc if they are in a hurry.
--------------------------------------------------------------------------
	Writing a LDP document by David S. Lawyer

The LDP need more writers to document Linux for the benefit of the
Linux community.  What you write will be put on hundreds of mirror
sites throughout the world for others to read (and download).  Pick a
Linux topic that lacks good free documentation.  Post your intentions
to: ####@####.#### so that we know what you are up to.  When
you've finished writing, submit it to: ####@####.####  We'll
read it over and if it's OK it gets put into our collection.  Read the
Guidelines below.

Guidelines for Writing a HOWTO, etc.:

*Use meaningful structure and organization, and write
 clearly.  Many of the people reading HOWTOs will not know English
 well, so avoid jargon, etc. that they might not understand.

*You must use a markup language, either LinuxDoc or DocBook.
 LinuxDoc is by far the easiest to use and learn but it's not nearly
 as advanced as DocBook.  For LinuxDoc see the mini-HOWTO:
 Howtos-with-LinuxDoc.  For DocBook see the LDP-Author-Guide.  Writing
 in such a markup language allows us to convert your writing into
 webpages (html), plain text, and other formats.  To insure that your
 markup is done correctly, you should try to convert it into plain
 text and html on your Linux PC.  Your could use another HOWTO as a
 model (template).
	Fix-me: add urls above.  

*You will own the copyright to what you write but you must select a
 license that meets this criteria (in the Manifesto):
 "Anyone may copy and distribute (sell or give away) LDP documents (or
 other LDP works) in any media and/or format.  No fees are required to
 be paid to the authors.  It is not required that the documents be
 modifiable, but it is encouraged."  You could use the boilerplate
 license in the Manifesto, the  GFDL license, or the Open Publication
 License (without options A or B).

	Fix-me: add urls above.  

*Make sure that all of the information is correct.  When in doubt,
 investigate.  If necessary, make it clear to the reader that you are
 not completely sure.

*Make sure that your name, email address, date, and a version
 number is near the beginning of the document. The standard header is
 for example:
  The Linux-System-HOWTO
  by John Doe ####@####.####
  v2.10.29, 31 May 2003

*Readers of your HOWTO will email you questions and suggestions.
These should be helpful in maintaining your HOWTO (which you need to
do to keep it up-to-date).  But you are under no obligation to provide
free support for people with problems, especially if the problem is
beyond the scope of the HOWTO or is poorly described.  You are also
likely to get spam, which can be mostly filtered out.  Scrambling your
email address to avoid spam will not permit others to email you with
just a click of the mouse.   I don't recommended it, but do it if you
must.

This one time, at band camp, David Lawyer ####@####.#### wrote:
> I've just rapidly written a one-page replacement for the
> LDP-Author-Guide.  The Guide is far too long and is intimidating for
> most people that are thinking of writing a HOWTO, etc.  It may take
> longer to read the Guide and digest it than to write a short HOWTO.

I agree, if I didn't already know DocBook I wouldn't have been able to 
write anything by reading the guide. IMO, it is way too long for the 
subject matter it covers.

--
You said homosexuals form a small percentage of the population.  So
do Jews.  Is that a reason to deny someone equality?
 - Richard Marceau

I think what will keep even more people from writing anything is the
lack of a free, simple to use WYSIWYG DocBook editor. Or did I miss
anyhting any anyone can recommend one. If so, why not put it in the
guide.

I know about all the DocBook modules for emacs, about XML modes for
editors, etc. but that I envision is something that is as easy to use as
a word processor but is just able to read and write DocBook.

What comes closest to my knowledge is AbiWord (a free cross-platform
work processor) that has some DocBook import and export filters, but
they are more experimental. At least they were last time I was looking
at them.

Torsten

-----Ursprüngliche Nachricht-----
Von: Morgon Kanter ####@####.#### 
Gesendet: Mittwoch, 30. April 2003 01:10
An: ####@####.####
Betreff: Re: One-page replacement for LDP-Author-Guide (not exactly, but
...)

This one time, at band camp, David Lawyer ####@####.#### wrote:
> I've just rapidly written a one-page replacement for the
> LDP-Author-Guide.  The Guide is far too long and is intimidating for
> most people that are thinking of writing a HOWTO, etc.  It may take
> longer to read the Guide and digest it than to write a short HOWTO.

I agree, if I didn't already know DocBook I wouldn't have been able to 
write anything by reading the guide. IMO, it is way too long for the 
subject matter it covers.

--
You said homosexuals form a small percentage of the population.  So
do Jews.  Is that a reason to deny someone equality?
 - Richard Marceau

______________________
http://lists.tldp.org/

On Thu, May 01, 2003 at 10:45:21PM +0200, Torsten Schlabach wrote:
> I think what will keep even more people from writing anything is the
> lack of a free, simple to use WYSIWYG DocBook editor. Or did I miss
> anything any anyone can recommend one. If so, why not put it in the
> guide.

If you tell people they will need to learn to use a new editor to write
for the LDP, then many people will be turned off and not do it.  But if you
tell them that they can use the same editor that they now use (with
several simple macros for LinuxDoc tags), then I think more are likely
to try it, especially if you can explain in a few pages by example what
the tags do.  Presenting both options: LinuxDoc or a simple new editor
designed for DocBook would be even better.

			David Lawyer

not to start a new flame war, but the switch from linuxdoc to docbook 
was not precisely a good idea...

time ago, using any vi/emacs or LyX to make linuxdoc was very simple. 
even if this format is still supported it's only with restrictions. I 
would probably never have done any HOWTO if I had not linuxdoc (and used 
it for many others docs)

there was only a slight lack of graphics and tables but that could 
easily be corrected.

today I am still reluctant to update my HOWTO given I must fight with 
docbook :-(

jdd

-- 
<http://www.dodin.net>
Formation Linux débutants open

Greg Ferguson wrote:

> It just so happens that the majority of the documents we now receive
> are in DocBook (XML or SGML), but Linuxdoc is certainly supported and
> welcome!

I knox ldp is very friendly, but I use to manage myself my documents and 
dislike to see my own web site one different from the ldp one (even for 
as little as revhistory tags - although if I don't update these tags my 
self, they a plain unusefull).

I think that at a moment or an other (but surely not soon) anyboby will 
be able to write his HOWTOs inline on the ldp site and with full xml 
capabilities (not text wiki). may be when the lampada successor will be 
out there.

anyway, a great document processor will come, probably from 
OpenOffice/koffice/??? that will do all the job for all. I for sure see 
an xml editor as powerfull as LaTeX is, in the few year from us.

Open Source is really great.

jdd

-- 
<http://www.dodin.net>
Formation Linux débutants open

There is a way to make OpenOffice work with DocBook DTD. You can find the
configuration details on their website.


Also, I hate to say this, but MS Office will be supporting XML, in its
professional version (not standard). :)

In Peace,
Saqib Ali
http://www.seagate.com/cheetah/


                                                                                                                                 
                      jdd                                                                                                        
                      ####@####.####        To:       ####@####.####                                                           
                      et>                      cc:       ####@####.####                                                     
                      No Phone Info            Subject:  Re: One-page replacement for LDP-Author-Guide (not exactly, but ...)    
                      Available                                                                                                  
                                                                                                                                 
                      05/02/2003 07:55                                                                                           
                      AM                                                                                                         
                                                                                                                                 
                                                                                                                                 




Greg Ferguson wrote:

> It just so happens that the majority of the documents we now receive
> are in DocBook (XML or SGML), but Linuxdoc is certainly supported and
> welcome!

I knox ldp is very friendly, but I use to manage myself my documents and
dislike to see my own web site one different from the ldp one (even for
as little as revhistory tags - although if I don't update these tags my
self, they a plain unusefull).

I think that at a moment or an other (but surely not soon) anyboby will
be able to write his HOWTOs inline on the ldp site and with full xml
capabilities (not text wiki). may be when the lampada successor will be
out there.

anyway, a great document processor will come, probably from
OpenOffice/koffice/??? that will do all the job for all. I for sure see
an xml editor as powerfull as LaTeX is, in the few year from us.

Open Source is really great.

jdd

--
<http://www.dodin.net>
Formation Linux débutants open



______________________
http://lists.tldp.org/

On Fri, 2003-05-02 at 07:55, jdd wrote:
> I think that at a moment or an other (but surely not soon) anyboby will 
> be able to write his HOWTOs inline on the ldp site and with full xml 
> capabilities (not text wiki). may be when the lampada successor will be 
> out there.

Someone I know is writing something like this using PHP and integrating
DocBook for creation of documents via a web page.  Since he's got to
develop this for his work anyway, he's taking my suggestions so that he
can make it something the LDP would be interested in having.

My ideal would be to have an online editor that would allow the user to
choose from Linuxdoc or DocBook (I know there are issues with this but I
think that since they are both officially supported they should both be
made available).  It ought to be smart enough to prompt for the type of
document and then insert the appropriate taggage on the user's behalf. 
Then, working in an outline method, an author could first create the
chapter/section names, and then start inserting content, with
lists/menus of tags nearby for formatting the text.  On the back end the
appropriate scripts would be in place to parse the document, confirm
it's validity, and process it into other formats.  Version control could
be built-in, as could a management database to keep stats and info
regarding reviews.

Just a little dream I have!  I imagine it will be built anyway, whether
the LDP uses it or not, but I sure hope it could be a tool that would
help authors who are not comfortable with any type of markup, or who
lack the tools (for whatever reason) to work in this manner.  

Though I can't say when something like this would happen, maybe it's
incentive enough for other PHPers out there who are fluent in
DocBook/Linuxdoc to band together and see what can be created based on
this idea.  I believe it would be an excellent resource for the LDP.

-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

Tabatha Persad wrote:
> On Fri, 2003-05-02 at 07:55, jdd wrote:
> 
>>I think that at a moment or an other (but surely not soon) anyboby will 
>>be able to write his HOWTOs inline on the ldp site and with full xml 
>>capabilities (not text wiki). may be when the lampada successor will be 
>>out there.
> 
> 
> Someone I know is writing something like this using PHP and integrating
> DocBook 

you dreamed it, the LDP does it :-)

jdd

-- 
<http://www.dodin.net>
Formation Linux débutants open

Since you mentioned online editor, take a look at this

http://www.ektron.com/ewebeditproxml.cfm?doc_id=2380


In Peace,
Saqib Ali
http://www.seagate.com/cheetah/


                                                                                                                                 
                      Tabatha Persad                                                                                             
                      <tabatha@merlinmo        To:       ####@####.####                                                     
                      nroe.com>                cc:                                                                               
                      No Phone Info            Subject:  Re: One-page replacement for LDP-Author-Guide (not exactly, but   ...)  
                      Available                                                                                                  
                                                                                                                                 
                      05/02/2003 11:17                                                                                           
                      AM                                                                                                         
                      Please respond to                                                                                          
                      tabatha                                                                                                    
                                                                                                                                 
                                                                                                                                 




On Fri, 2003-05-02 at 07:55, jdd wrote:
> I think that at a moment or an other (but surely not soon) anyboby will
> be able to write his HOWTOs inline on the ldp site and with full xml
> capabilities (not text wiki). may be when the lampada successor will be
> out there.

Someone I know is writing something like this using PHP and integrating
DocBook for creation of documents via a web page.  Since he's got to
develop this for his work anyway, he's taking my suggestions so that he
can make it something the LDP would be interested in having.

My ideal would be to have an online editor that would allow the user to
choose from Linuxdoc or DocBook (I know there are issues with this but I
think that since they are both officially supported they should both be
made available).  It ought to be smart enough to prompt for the type of
document and then insert the appropriate taggage on the user's behalf.
Then, working in an outline method, an author could first create the
chapter/section names, and then start inserting content, with
lists/menus of tags nearby for formatting the text.  On the back end the
appropriate scripts would be in place to parse the document, confirm
it's validity, and process it into other formats.  Version control could
be built-in, as could a management database to keep stats and info
regarding reviews.

Just a little dream I have!  I imagine it will be built anyway, whether
the LDP uses it or not, but I sure hope it could be a tool that would
help authors who are not comfortable with any type of markup, or who
lack the tools (for whatever reason) to work in this manner.

Though I can't say when something like this would happen, maybe it's
incentive enough for other PHPers out there who are fluent in
DocBook/Linuxdoc to band together and see what can be created based on
this idea.  I believe it would be an excellent resource for the LDP.

--
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)



______________________
http://lists.tldp.org/