* Date: Fri, 10 Aug 2007 09:40:47 +0200
* Sam Ravnborg:
>
> Documentation should be easy to access and readable in the source format.
> For this purpose asciidoc seems to do a good job.
>
> It is btw. discussed at git ML if they should shift due to toolset being
> slow but that happens to be the do
Sam Ravnborg wrote:
> On Sun, Aug 12, 2007 at 03:10:57PM +0200, Stefan Richter wrote:
>> One note on asciidoc: I experienced the same as Willy when I wanted to
>> build git with manpages on a distribution without prebuilt asciidoc.
>
> I assume you had troubles with the docbook utilities and not
On Sun, Aug 12, 2007 at 03:10:57PM +0200, Stefan Richter wrote:
>
> One note on asciidoc: I experienced the same as Willy when I wanted to
> build git with manpages on a distribution without prebuilt asciidoc.
I assume you had troubles with the docbook utilities and not asciidoc itself.
asciidoc
Randy Dunlap wrote:
> On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
>> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
>>> I was just suggesting that if we took your suggestion of standardizing
>>> on plain text plus some conventions for formatting lists and headers and
>
On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:
> >
> > What primary requirements does in-tree Linux kernel documentation have
> > to fulfill in general?
>
> Skipping the obvious ones such as correct, up-to-date etc.
> o Readable as-is
> o Grepable
> o buildable as structured documents or
On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> > On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > > The problem I have with asciidoc is that it's a nightmare to get it
> > > to work. It's what GIT uses,
On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote:
> Hi Stephen,
>
> On Thu, Aug 09, 2007 at 11:31:22AM +0100, Stephen Hemminger wrote:
> > Since the network device documentation needs a rewrite, I was thinking
> > of using basic html format instead of just plain text. But since this would
>
> Hi Sam,
>
> Sorry for the late question (I've been away :).
>
> Was your makefiles.txt conversion done totally by hand?
Yes. A few search&replace, the rest manual.
> Could it be automated?
For text with a unifom structure like makefiles.txt - yes.
Sam
-
To unsubscribe from this list:
On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> > On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > > The problem I have with asciidoc is that it's a nightmare to get it
> > > to work. It's what GIT uses,
On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote:
> Hi Stephen,
>
> On Thu, Aug 09, 2007 at 11:31:22AM +0100, Stephen Hemminger wrote:
> > Since the network device documentation needs a rewrite, I was thinking
> > of using basic html format instead of just plain text. But since this would
>
On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:
> >
> > What primary requirements does in-tree Linux kernel documentation have
> > to fulfill in general?
>
> Skipping the obvious ones such as correct, up-to-date etc.
> o Readable as-is
> o Grepable
> o buildable as structured documents or
On 08/11/2007 08:31 AM, Stefan Richter wrote:
Rene Herman wrote:
On 08/10/2007 10:12 PM, Sam Ravnborg wrote:
What primary requirements does in-tree Linux kernel documentation have
to fulfill in general?
Skipping the obvious ones such as correct, up-to-date etc.
o Readable as-is
o Grepable
o
On Aug 10 2007 22:12, Sam Ravnborg wrote:
>Asciidoc is quite close to plaintext and it looks to me that the
>formatting possibilities are quite good.
How about mediwiki text?
'''Users'''
:are people who build kernels.
'''Normal developers'''
:are this and that
>+=== Goal definitions
>+
>+
On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > The problem I have with asciidoc is that it's a nightmare to get it
> > to work. It's what GIT uses, and after spending a whole day trying
> > to *build* that thing,
On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> The problem I have with asciidoc is that it's a nightmare to get it
> to work. It's what GIT uses, and after spending a whole day trying
> to *build* that thing, I finally resigned and asked Junio if he could
> publish the pre-formatt
Rene Herman wrote:
> On 08/10/2007 10:12 PM, Sam Ravnborg wrote:
>
>>> What primary requirements does in-tree Linux kernel documentation have
>>> to fulfill in general?
>>
>> Skipping the obvious ones such as correct, up-to-date etc.
>> o Readable as-is
>> o Grepable
>> o buildable as structured d
On Sat, Aug 11, 2007 at 01:08:30AM +0200, Sam Ravnborg wrote:
> >
> > The problem I have with asciidoc is that it's a nightmare to get it
> > to work. It's what GIT uses, and after spending a whole day trying
> > to *build* that thing, I finally resigned and asked Junio if he could
> > publish the
On 08/10/2007 10:12 PM, Sam Ravnborg wrote:
What primary requirements does in-tree Linux kernel documentation have
to fulfill in general?
Skipping the obvious ones such as correct, up-to-date etc.
o Readable as-is
o Grepable
o buildable as structured documents or almost like a single book
o Ea
>
> The problem I have with asciidoc is that it's a nightmare to get it
> to work. It's what GIT uses, and after spending a whole day trying
> to *build* that thing, I finally resigned and asked Junio if he could
> publish the pre-formatted manpages himself, which he agreed to.
Bit uses in additi
On Fri, Aug 10, 2007 at 04:40:25PM -0400, J. Bruce Fields wrote:
> On Fri, Aug 10, 2007 at 10:17:04PM +0200, Willy Tarreau wrote:
> > I've read pro-plain text arguments, so I'll not repeat them. I also see
> > another advantage to plain text : it's very easy to draw ascii-art
> > diagrams of anythi
On Fri, Aug 10, 2007 at 10:17:04PM +0200, Willy Tarreau wrote:
> I've read pro-plain text arguments, so I'll not repeat them. I also see
> another advantage to plain text : it's very easy to draw ascii-art
> diagrams of anything. It only takes a few minutes, is always inline
> and readable with any
Hi Stephen,
On Thu, Aug 09, 2007 at 11:31:22AM +0100, Stephen Hemminger wrote:
> Since the network device documentation needs a rewrite, I was thinking
> of using basic html format instead of just plain text. But since this would
> be starting an new precedent for kernel documentation, some it see
>
> What primary requirements does in-tree Linux kernel documentation have
> to fulfill in general?
Skipping the obvious ones such as correct, up-to-date etc.
o Readable as-is
o Grepable
o buildable as structured documents or almost like a single book
o Easy to replicate structure
o Maintainable
Sam Ravnborg wrote:
> On Thu, Aug 09, 2007 at 05:26:13PM +0200, Andi Kleen wrote:
>> Also I would expect much more people will know how to write html versus
>> DocBook.
>
> Documentation should be easy to access and readable in the source format.
> For this purpose asciidoc seems to do a good job.
On Thu, Aug 09, 2007 at 05:26:13PM +0200, Andi Kleen wrote:
> Hans-Jürgen Koch <[EMAIL PROTECTED]> writes:
>
> > Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:
> > > Since the network device documentation needs a rewrite, I was thinking
> > > of using basic html format instead of ju
On 08/10/2007 12:27 AM, Francois Romieu wrote:
Andi Kleen <[EMAIL PROTECTED]> :
[...]
I don't think that is used by Linuxdoc. Try a make pdfdocs and see for
yourself.
It reminds me of an old PII but it does not really make clear how html to
pdf conversion would improve the situation.
With
Andi Kleen <[EMAIL PROTECTED]> :
[...]
> I don't think that is used by Linuxdoc. Try a make pdfdocs and see
> for yourself.
It reminds me of an old PII but it does not really make clear how
html to pdf conversion would improve the situation.
--
Ueimor
-
To unsubscribe from this list: send the li
On Aug 9 2007 22:03, Jesper Juhl wrote:
>On 09/08/07, Stephen Hemminger <[EMAIL PROTECTED]> wrote:
>> Since the network device documentation needs a rewrite, I was thinking
>> of using basic html format instead of just plain text. But since this would
>> be starting an new precedent for kernel doc
On 09/08/07, Stephen Hemminger <[EMAIL PROTECTED]> wrote:
> Since the network device documentation needs a rewrite, I was thinking
> of using basic html format instead of just plain text. But since this would
> be starting an new precedent for kernel documentation, some it seemed
> like a worthwhil
On 8/9/07, Stefan Richter <[EMAIL PROTECTED]> wrote:
> Stephen Hemminger wrote:
> > Advantages of html:
> > * basic formatting like lists, italics, etc
>
> Plaintext has lists too. See for example
> <[EMAIL PROTECTED]>. ;-)
>
> It's also possible to approximate bold face, italics, and underline
> xsltproc converts from docbook to html fast enough (PDF with a docbook
I don't think that is used by Linuxdoc. Try a make pdfdocs and see
for yourself.
-Andi
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo in
Stephen Hemminger wrote:
> Advantages of html:
> * basic formatting like lists, italics, etc
Plaintext has lists too. See for example
<[EMAIL PROTECTED]>. ;-)
It's also possible to approximate bold face, italics, and underlines in
plaintext.
> * easier to integrate into other places and re
Andi Kleen <[EMAIL PROTECTED]> :
[...]
> I would say the track record of existing DocBook deployment is not good enough
> to justify further use. Plain html can be converted into all these
> formats easily too and overall it makes a much nicer user experience.
xsltproc converts from docbook to htm
On 8/9/07, Stephen Hemminger <[EMAIL PROTECTED]> wrote:
> Since the network device documentation needs a rewrite, I was thinking
> of using basic html format instead of just plain text. But since this would
> be starting an new precedent for kernel documentation, some it seemed
> like a worthwhile
On 09-08-2007 17:26, Andi Kleen wrote:
> Hans-Jürgen Koch <[EMAIL PROTECTED]> writes:
>
>> Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:
>>> Since the network device documentation needs a rewrite, I was thinking
>>> of using basic html format instead of just plain text.
>> Why don
On 08/09/2007 05:26 PM, Andi Kleen wrote:
In my experience it tends to be challenging to actually find all the packages
needed for that. And then it's incredibly slow -- seems to be much slower
than gcc which is somewhat of an archivement. And at least for LinuxDoc TeX usually
can't even compil
Hans-Jürgen Koch <[EMAIL PROTECTED]> writes:
> Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:
> > Since the network device documentation needs a rewrite, I was thinking
> > of using basic html format instead of just plain text.
>
> Why don't you simply use DocBook? Then the user h
On Thu, 9 Aug 2007, Jan Engelhardt wrote:
> On Aug 9 2007 14:34, Bodo Eggert wrote:
> >I don't think and should be used, instead you should use styles
> >( etc).
>
> does the same as , and the latter is much
> more verbose for the same thing.
You shoud use neither. It's OK on homepages, but f
On Thu, 9 Aug 2007 15:08:20 +0200
Hans-Jürgen Koch <[EMAIL PROTECTED]> wrote:
> Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:
> > Since the network device documentation needs a rewrite, I was thinking
> > of using basic html format instead of just plain text.
>
> Why don't you si
Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:
> Since the network device documentation needs a rewrite, I was thinking
> of using basic html format instead of just plain text.
Why don't you simply use DocBook? Then the user has the choice to convert
to HTML, PDF, LaTex or whatever
On Aug 9 2007 14:34, Bodo Eggert wrote:
>
>I don't think and should be used, instead you should use styles
>( etc).
does the same as , and the latter is much
more verbose for the same thing.
>Things like and should be OK, if used consistently.
>
>> Perhaps maybe with .block{text-align:just
Jan Engelhardt <[EMAIL PROTECTED]> wrote:
> On Aug 9 2007 11:31, Stephen Hemminger wrote:
>>Since the network device documentation needs a rewrite, I was thinking
>>of using basic html format instead of just plain text. But since this would
>>be starting an new precedent for kernel documentation,
On Aug 9 2007 11:31, Stephen Hemminger wrote:
>
>Since the network device documentation needs a rewrite, I was thinking
>of using basic html format instead of just plain text. But since this would
>be starting an new precedent for kernel documentation, some it seemed
>like a worthwhile topic for d
Since the network device documentation needs a rewrite, I was thinking
of using basic html format instead of just plain text. But since this would
be starting an new precedent for kernel documentation, some it seemed
like a worthwhile topic for discussion.
Advantages of html:
* basic formatting
44 matches
Mail list logo
