The Power to Serve – FreeBSD Power Management • Hacker News Board

Re: The Power to Serve – FreeBSD Power Management

#21

Post by bkor » Thu, Nov 29, 2018, 2:33 PM UTC

rleigh wrote: post #13

int_19h wrote: post #9

Earlier quoted context omitted.

It's written in DocBook, which is hardly obscure.

No, but it is horribly verbose and a pain to work with. I personally find the flow of writing to be constantly interrupted with the demand to mark everything up just so, and for very technical documents with a lot of markup, the markup can dwarf the content several times over! While they are less powerful, markdown, restructured text and other simpler markup languages are much more productive to work with. They are e…

An alternative to retext is Mallard. It's pretty easy to use, see http://projectmallard.org/. It's used within GNOME for the documentation.

Re: The Power to Serve – FreeBSD Power Management

#22

Post by mdtancsa » Thu, Nov 29, 2018, 2:38 PM UTC

vermaden wrote: post #5

AndrewBissell wrote: post #3

Earlier quoted context omitted.

When I was playing with FreeBSD a lot in late 2017/early 2018, I had a ton of time wasted following outdated chapters in the Handbook. It became very frustrating once I found the 7th or 8th "this part of the Handbook is outdated" post on the FreeBSD forums. Kinda funny, because the Handbook is often touted as something which is supposed to make it very welcoming to beginners.

The FreeBSD Handbook is generally very well written but for parts that change often or that are 'less popular' it could be managed little better.

IPSEC is a good example where its lacking. Its in desperate need to be updated with modern config examples and documentation, especially with newer keying daemons like FreeSWAN. Maybe the time gods will be kind to me in December and I can find cycles to make a start at it rather than moan from the sidelines :)

Re: The Power to Serve – FreeBSD Power Management

#23

Post by rleigh » Thu, Nov 29, 2018, 2:51 PM UTC

bkor wrote: post #21

rleigh wrote: post #13

Earlier quoted context omitted.

No, but it is horribly verbose and a pain to work with. I personally find the flow of writing to be constantly interrupted with the demand to mark everything up just so, and for very technical documents with a lot of markup, the markup can dwarf the content several times over! While they are less powerful, markdown, restructured text and other simpler markup languages are much more productive to work with. They are e…

An alternative to retext is Mallard. It's pretty easy to use, see http://projectmallard.org/ . It's used within GNOME for the documentation.

Thanks, I took a quick look. However, it appears to be XML-based markup not too different from HTML or DocBook. So I don't see this having the benefits which lightweight markup provides. It has all of the same disadvantages of HTML and DocBook in terms of the markup verbosity from what I can tell.

Which isn't to say it's not very good at what it does, just that I can't see a compelling difference over DocBook or HTML.

Re: The Power to Serve – FreeBSD Power Management

#24

Post by int_19h » Thu, Nov 29, 2018, 8:27 PM UTC

rleigh wrote: post #13

int_19h wrote: post #9

Earlier quoted context omitted.

It's written in DocBook, which is hardly obscure.

No, but it is horribly verbose and a pain to work with. I personally find the flow of writing to be constantly interrupted with the demand to mark everything up just so, and for very technical documents with a lot of markup, the markup can dwarf the content several times over! While they are less powerful, markdown, restructured text and other simpler markup languages are much more productive to work with. They are e…

The nice thing about DocBook is that, because of how strictly structured it is, there are visual editors for it that provide experience far superior to anything that can be had with Markdown etc, especially for large quantities of documentation. I would dare say that it's also easier for beginners that way, too.