<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8">
<META NAME="GENERATOR" CONTENT="GtkHTML/3.26.0">
</HEAD>
<BODY>
On Sat, 2010-05-15 at 22:39 +0200, Rémi Cardona wrote:
<BLOCKQUOTE TYPE=CITE>
<PRE>
Le 14/05/2010 22:50, Gaetan Nadon a écrit :
> The linuxdoc doc tool is deprecated.
> README files are exclusively text files.
> The file had not been updated for 5 years.
Is that file worth keeping and maybe converting to docbook like Alan did
for the internal server doc?
</PRE>
</BLOCKQUOTE>
I have been asking my self that question and counting on this review for opinions. What tipped the balance (for me):<BR>
<BR>
- The drivers appear not to be under development, so the file gets rarely changed<BR>
- The file is almost all plain text (little or no formatting) except for the generated toc.<BR>
- Plain text is acceptable for a README file<BR>
- docbook sgml is also a deprecated format. Conversion to Docbook xml is not straightforward.<BR>
<BR>
If we want to retain the marked-up source, I would put it (renamed) in a /doc and have it installed. I don't like the current manual half-generated half-git solution.<BR>
<BR>
<TABLE CELLPADDING="0">
<TR>
<TH NOWRAP ALIGN="right" VALIGN="top">
<B>From: </B>
</TH>
<TD>
Alan Coopersmith <<A HREF="mailto:Alan%20Coopersmith%20%3cAlan.Coopersmith@Sun.COM%3e">Alan.Coopersmith@Sun.COM</A>>
</TD>
</TR>
<TR>
<TH NOWRAP ALIGN="right" VALIGN="top">
<DIV ALIGN=right><B>To: </B></DIV>
</TH>
<TD>
X.Org Developers <<A HREF="mailto:%22X.Org%20Developers%22%20%3cxorg-devel@lists.x.org%3e">xorg-devel@lists.x.org</A>>
</TD>
</TR>
<TR>
<TH NOWRAP ALIGN="right" VALIGN="top">
<B>Subject: </B>
</TH>
<TD>
X.Org documentation formats, plans, conversions, etc.
</TD>
</TR>
<TR>
<TH NOWRAP ALIGN="right" VALIGN="top">
<DIV ALIGN=right><B>Date: </B></DIV>
</TH>
<TD>
Tue, 10 Nov 2009 21:40:32 -0800 <I>(Wed, 00:40 EST)</I>
</TD>
</TR>
</TABLE>
<BLOCKQUOTE>
<PRE>
<TT><FONT COLOR="#1a1a1a">At this point, these are the documentation input and output formats I know of:</FONT></TT>
<TT><FONT COLOR="#1a1a1a">Preferred output formats:</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - man pages for commands and public API in client-side libraries,</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> to be installed in $(mandir)</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - plain text, html & pdf for specifications and other documents,</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> to be installed in $(docdir) & published on the website</FONT></TT>
<TT><FONT COLOR="#1a1a1a">Preferred input formats:</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - DocBook/XML (can generate man, text, html & pdf)</FONT></TT>
<TT><FONT COLOR="#1a1a1a">Acceptable input formats:</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - AsciiDoc (can generate DocBook, thus all DocBook supports)</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - Plain text</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - man pages in troff -man format</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - doxygen comments in source code</FONT></TT>
<TT><FONT COLOR="#1a1a1a">Deprecated input formats (no new docs should be added in these):</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - troff -ms/-mm</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - FrameMaker</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - LinuxDoc</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - DocBook/SGML</FONT></TT>
<TT><FONT COLOR="#1a1a1a"> - TeX</FONT></TT>
</PRE>
</BLOCKQUOTE>
<BR>
<BLOCKQUOTE TYPE=CITE>
<PRE>
Cheers,
Rémi
_______________________________________________
<A HREF="mailto:xorg-devel@lists.x.org">xorg-devel@lists.x.org</A>: X.Org development
Archives: <A HREF="http://lists.x.org/archives/xorg-devel">http://lists.x.org/archives/xorg-devel</A>
Info: <A HREF="http://lists.x.org/mailman/listinfo/xorg-devel">http://lists.x.org/mailman/listinfo/xorg-devel</A>
</PRE>
</BLOCKQUOTE>
</BODY>
</HTML>