Tools for writers

classic Classic list List threaded Threaded
77 messages Options
1234
Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Xiánwén Chén
Dear Ingo,

> Could I have a copy of the source text file of the presentation and the
> command line(s) that produced the PDF file?

I found it: https://www.openbsd.org/papers/eurobsdcon2018-mandoc.roff

Yours sincerely,
Xianwen

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Martijn van Duren-6
In reply to this post by Steve Litt
On 11/6/19 12:07 AM, Steve Litt wrote:

> On Tue, 5 Nov 2019 23:12:52 +0100
> Ingo Schwarze <[hidden email]> wrote:
>
>  
>> https://www.openbsd.org/papers/bsdcan18-mandoc.pdf
>
> If the preceding presentation was authored in mdoc(7), could  you please
> post the mdoc code that created it, and the mandoc(1) command and any
> filter programs that caused it to be a presentation instead of a man
> page?

You mean this one?
https://www.openbsd.org/papers/bsdcan18-mandoc.roff

There are more examples at:
https://www.openbsd.org/events.html

martijn@

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Ingo Schwarze
Hi,

Martijn van Duren wrote on Wed, Nov 06, 2019 at 06:40:51AM +0100:
> On 11/6/19 12:07 AM, Steve Litt wrote:
>> On Tue, 5 Nov 2019 23:12:52 +0100

>>> https://www.openbsd.org/papers/bsdcan18-mandoc.pdf

>> If the preceding presentation was authored in mdoc(7), could  you please
>> post the mdoc code that created it, and the mandoc(1) command and any
>> filter programs that caused it to be a presentation instead of a man
>> page?

> You mean this one?
> https://www.openbsd.org/papers/bsdcan18-mandoc.roff

Exactly.  Note that it does not use mdoc(7), though, but textproc/gpresent
(groff_present(7)) on top of groff_mm(1) and roff(7).

The mdoc(7) macro set has a very narrow scope: documentation.  It
isn't adequate for anything else, in particular neither presentations
nor books nor even short journal articles.  On the other hand,
roff(7) can be used for any kind of typesetting, usually with one
of the other macro sets.  The most modern and most actively maintained
of the general purpose macro sets is Peter Schaffter's groff_mom(7).

Also note that i did not say pandoc is useless; all i intended to
say is that if you need to write documentation, *that* is not a
good reason to look at pandoc - merely because somebody on this
list recommended pandoc specifically for writing documentation,
which seems very misleading to me.

> There are more examples at:
> https://www.openbsd.org/events.html

True.  When it comes to gpresent, examples are arguably easier to
find in this shorter list:

  http://mandoc.bsd.lv/press.html

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Marc Chantreux
In reply to this post by Ingo Schwarze
hello,

> https://www.openbsd.org/papers/bsdcan18-mandoc.pdf

which leds me to the conference video. it was really interesting.

> Nothing is wrong with trying to make things simple for users, quite
> to the contrary.  But that is not an excuse for delivering solutions
> that are technically abominable.

ok. now i get your honorable point but the lazy part of me will take its
part of abomination to get things done in a pleasant way :)

also: i didn't dive that much in pandoc code but from what i saw:
even a non-fluent haskell person which i am can read this code.

> When a language is technically
> as ill-designed as markdown is, the multitude of resulting traps
> actually makes it very hard to use, *not* easy at all.

well ... i really think this is a bias because i really think markdown
is so easy to use it popularized the use of wiki syntaxes (which mean
less use of wysiwyg tools ... which is more abominable).

let me ruin your day: are you aware of scdoc?

    https://git.sr.ht/~sircmpwn/scdoc

i really appreciated reading about you opinion. thank you.

regards
marc

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Ingo Schwarze
In reply to this post by Steve Litt
Hi Steve,

Steve Litt wrote on Tue, Nov 05, 2019 at 06:38:52PM -0500:
> On Tue, 5 Nov 2019 18:38:03 +0100 > Ingo Schwarze wrote:
>> Andrew wrote on Sun, Nov 03, 2019 at 12:56:58PM +0000:

>> [ Pandoc ]
>>> is one of the most useful tools I have ever used.  If you are
>>> writing any sort of documentation then I *highly* recommend
>>> checking it out  

>> I strongly oppose that point.  

Admittedly, this was a bit of a diversion because the OP asked about
long, general-purpose texts like books - but all the same, it didn't
want to let the statement "pandoc is recommended for *documentation*"
go unchallenged.

[ mdoc(7) ]
> no method of creating a header hierarchy like <h1>...<h6>
> I'd suspect it could be done by nesting .Sh lines,

No, .Sh does not nest at all.

> no way to declare arbitrary styles.
> can't make new kinds of lists

That's all perfectly true.  The mdoc(7) macro set serves a very
narrow domain: documentation, i.e. manual pages.  It's intentionally
neither configurable nor extensible.  The goal is to enforce a
uniform style on manual pages, optimized for simplicity, conciseness,
and clarity, but without manual page authors having to worry about
the styling at all, in fact not even allowing authors to mess with
that uniform style of manual pages, such that all pages follow the
same conventions and readers can quickly become familiar with these
conventions.

> If I'm wrong, I might start writing my books in mdoc(7).

Please don't even try.  Writing a book in mdoc(7) is completely
impossible for lots and lots of reasons.  For a book, i guess that
the groff_mom(7) macro set might be useful.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Ingo Schwarze
In reply to this post by Marc Chantreux
Hi Marc,

Marc Chantreux wrote on Wed, Nov 06, 2019 at 08:42:28AM +0100:

> let me ruin your day: are you aware of scdoc?
>     https://git.sr.ht/~sircmpwn/scdoc

Yes, i think i tripped over it before, once.

> i really appreciated reading about you opinion. thank you.

I think the basic idea is a thoroughly bad one:  targetting man(7)
as an output language is already a dubious choice.  On the one hand,
man(7) can be considered an ancient, obsolete language.  It was the
state of the art from 1979 to about 1990 and has now been obsolete
for almost three decades.

Admittedly, there are still unusual circumstances where you need it,
not listing them here.  But in that case, it can and should be written
by hand.  Yes, it is more difficult than mdoc(7) or perlpod(1) to
write, but not all *that* hard, so a wrapper language is not really
needed.

With the exception of perlpod(1)/pod2man(1), most programs that
autogenerate man(7) code produce low-quality output, so usually,
using a preprocessor is a bad idea because you get poor manual
page formatting.  scdoc(1) is not an exception; the output code
quality is poor indeed:

 * stray .P before and after .SH
 * incorrect usage of plain "-" in NAME line
 * weird ALL CAPS formatting for .SS
 * failure to use font macros, using font escapes instead
 * stray .P inside .RS/.RE
 * incorrect use of plain "-" for \(em
 * violation of "new sentence, new line"
 * missing double space after full stop
 * EXTREMELY poor formatting of bullet lists,
   totally failing to use .TP or .IP in nroff output mode,
   instead resorting to plain .nf
 * TERRIBLE gratuitions use of .ie n for lists with
   manual negative \h that doesn't even work reliably
   in a portable way; while it does work with groff(1),
   it doesn't with mandoc(1) or other formatters
 * relies on tbl(7) for tables, but without giving any instructions
   to the subsequent formatter to run the tbl(1) preprocessor;
   while that works with mandoc(1), it is not portable and fails
   by default even with groff(1)
 * produces UTF-8 characters embedded in man(7) code instead
   of properly encoding them as documented in groff_char(7) and
   mandoc_char(7); while that works with mandoc(1), it is not
   portable and fails by default even with groff(1)

There may be more problems with it, this list is just from one very
brief glance at the man(7) output generated from the scdoc.5.scd
manual page itself.

To summarize, there wasn't any need for yet another man(7)
autogenerator, perlpod(1) already existed, and while most man(7)
autogenerators are bad, this one may even be producing below-average
quality.

Besides, several of the points i made against Markdown appear to
apply to scdoc just as well (or rather, just as badly), in particular
context sensitivity/ambiguity, purely presentational markup and
lack of semantic markup, lack of language independence...

Do not use it.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Marc Chantreux
> With the exception of perlpod(1)/pod2man(1), most programs that

good to know as i'm really confortable with pod.

> page formatting.  scdoc(1) is not an exception; the output code
> quality is poor indeed
>  * stray .P before and after .SH
> ...

this list is really interesting. maybe it should be shared with
the scdoc project. it will not solve the problems but at least those
ones can be fixed.

> To summarize, there wasn't any need for yet another man(7)
> autogenerator, perlpod(1) already existed, and while most man(7)
> autogenerators are bad, this one may even be producing below-average
> quality.

my opinion is more blur: using a tool that works find is important but
i'm always happy when i can remove a usage of an interpreted
langage (even perl which was by far my prefered one before i started to use raku).

> Do not use it.

i wasn't even wanting to: this one was mostly a joke to tickle you then
it ends up to a really interesting and constructive answer. thanks a
lot.

marc

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Yon-2
In reply to this post by Ingo Schwarze
Hi,

On Wed, Nov 06, 2019 at 08:43:18AM +0100, Ingo Schwarze wrote:

> Hi Steve,
>
> Steve Litt wrote on Tue, Nov 05, 2019 at 06:38:52PM -0500:
> > On Tue, 5 Nov 2019 18:38:03 +0100 > Ingo Schwarze wrote:
> >> Andrew wrote on Sun, Nov 03, 2019 at 12:56:58PM +0000:
>
> >> [ Pandoc ]
> >>> is one of the most useful tools I have ever used.  If you are
> >>> writing any sort of documentation then I *highly* recommend
> >>> checking it out  
>
> >> I strongly oppose that point.  
>
> Admittedly, this was a bit of a diversion because the OP asked about
> long, general-purpose texts like books - but all the same, it didn't
> want to let the statement "pandoc is recommended for *documentation*"
> go unchallenged.
In my opinion, most of the points you made in the OpenBSD
Journal apply for novels too, and probably even more so for
technical books, but I can only judge for the first.

The fact that markdown is not semantic, but essentially
presentational, makes it impossible to make formatting
changes to a whole semantic category after the fact (e.g.
plant name, song title, place name), and impossible to
automatically extract that information from the file for
various purposes.  A fully featured apropos(1) is not
required for novels, but it's handy to at least be able to
extract a list of names from a specific semantic category,
whether to check it's correct, or to display it somewhere
else (like an index). It's also handy when translating a
work, to compare the original and translated version on
specific points, often catching mistakes.

But maybe the worst consequence of the markdown pitfalls you
mention, is that it cannot provide any kind of syntax error
reporting.  Markup languages have different needs than
programming languages.  For example favouring warnings (like
you did for mandoc(1)) is generally better than fatal errors
(like often LaTeX).  But no warnings (like markdown) is
worse than both.  Some people seem to think syntax
highlighting is enough to avoid formatting mistakes, but you
cannot depend on it when reading a diff, for example.  And
anyways, it's still easy to overlook a small formatting
error.

In my opinion, most of mandoc(1) design philosophy is worth
considering for non-documentation long works: diff and
grep-friendly simple non-ambiguous syntax, good non-fatal
warnings, mostly semantic and fast.  All of this seems good
for any big project.  When designing frundis(1) for novels,
it's been my main inspiration, though it falls short on one
point: due to the unpredictable requirements of creative
works, it's been simpler (unavoidable?) to not make it fully
self-contained.  At least, new macros can abstract target
format specific parts and make it fully-contained per
project, which is still better than markdown.

For long technical books, I don't think there's still
anything approaching what mandoc(1) is for documentation.
LaTeX and groff are good, but not semantic enough (making
non-PDF exports tricky), have a quite fragile syntax at
times and, in my experience, are not great at error
reporting - which may be because of current tools instead of
the languages themselves, though.

Yon

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Yon-2
In reply to this post by Steve Litt
On Tue, Nov 05, 2019 at 06:38:52PM -0500, Steve Litt wrote:

> > If you write documentation, just use the best format in the first
> > place.  If the project you are documenting allows checking in
> > documentation in mdoc(7) format, use that.
>
> TL/DR SUMMARY: mdoc(7) is cool, but based on an hour or so's research is
> insufficient for all but the simplest full length books.
>
> I've spent the last hour or so looking at man pages mandoc(1) and
> mdoc(7), and I currently don't see how a non-simple book could be
> authored in mdoc(7). First of all, I see no method of creating a header
> hierarchy like <h1>...<h6> or \part ... \subparagraph . I'd suspect it
> could be done by nesting .Sh lines, but I couldn't see how that could
> be done.
>
> As far as I can tell, mdoc(7) has no way to declare arbitrary styles.
> If I want a style called "stories", as an author I should be able to use
> one, and worry about semantic to presentational conversion of the
> stories style to be something I make later (with CSS or LaTeX or
> whatever). Almost by definition, if I can't create new semantic styles,
> I'll need to use or reuse predefined ones, which introduces ambiguity
> and mixing of semantic and presentational.
>
> Kudos for provisions to make a bibliography, and a TOC in HTML output.
>
> mdoc(7) supported lists cover a wide variety of presentations, but as
> far as I can tell you can't make new kinds of lists based on the
> existing lists. For instance, I might have a list for people with
> vertical spacing very different from a list for concepts, and I see no
> way to do that in mdoc(7) without declaring that all people are done
> with one kind of mdoc(7) list, and all concepts are done with another.
> Another problem: If I initially do both people and concepts with a
> certain mdoc(7) list type, and then decide people should look
> different, I'd have to search out all the people, instead of changing
> one line of CSS or one line of LaTeX.
Declaring arbitrary styles and semantics while being able to
produce HTML/EPUB and LaTeX was the main point of frundis.
I'll therefore provide some small examples, so that you may
research more if you want.

For example, you can define semantic tags for each format:

    .X mtag -f latex -t people -c emph
    .X mtag -f xhtml,epub -t people -c em

and then using them like:

    .Sm -t people Steve

which will be rendered as <em class="people">Steve</em> in
html, and \emph{Steve} in LaTeX.

There are different kind of semantic tags, whether for
phrasing elements or block/environment elements.  The
language provides common semantic elements for novels (4
header levels, TOC, links, cross-references), but it lacks
more advanced functionality, like built-in bibliographies.

When built-in functionality is not enough, you can wrap
LaTeX and HTML code with macros.  For example, you can write
the following macro hr in a file macros.frundis:

    .#de hr \" define macro hr
    .P
    .Bf -f xhtml \" when exporting to HTML
    <hr>
    .Ef
    .Bf -f latex \" when exporting to LaTeX
    \erule{\etextwidth}{1pt}
    .Ef
    .P
    .#. \" end of definition

Then you can use it in your main file:

    .If macros.frundis \" include macro definitions
    .hr

If this kind of extensibility sounds like enough for what
you need, you may have a look at the whole mdoc(7) man page
frundis_syntax(5):

https://bardinflor.perso.aquilenet.fr/frundis/frundis_syntax-5.html

That said, if your books are too technical, you may end up
needing to extend yourself the language too much. Or maybe
you'll hit some unexpected limitations that will probably
not disappear with time, as the language is feature complete
for its main intended usage.

Yon

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Oliver Leaver-Smith
In reply to this post by Oliver Leaver-Smith-2
Thanks everyone for recommendations, I think I am just going to use VimOutliner for development and outlining. The use case I have is for a novel which should require less formatting than a technical book, so I should be able to retrofit that after once I have investigated the many tools mentioned in the thread.

-ols
--
Oliver Leaver-Smith
+44(0)114 360 1337
TZ=Europe/London

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Damien Thiriet
In reply to this post by Oliver Leaver-Smith-2
Hi,


As an alternative to LaTeX, especially if you design the book,
you may give ConTeXt a chance. Just several elements of
comparison with LaTeX

Cons:

* quite hard learning-curve
* documentation is hard to find a the beginning.
  The reference manual is not maintained any more.
  Things are however better than three years ago: the ConTeXt excursion
  book has been updated. Official documentation is now split into
  manuals dealings with specific issues (tables, biblio, XML and so on).
* ConTeXt is a niche even inside the *TeX world.
* Publishers usually ask for LaTeX.
* You have to design your layout from scratch (no documentclass shiped,
  only paper format)


Pros:
* you don't need to upload packages, and check for incompabilities.
  I have been using it a lot for three years now, and never loaded any
  third-part module.
* bibliography out of the box, which is great since I could'nt have
  biber working on OpenBSD.
* metapost graphics out of the box. MP graphics compile faster than TikZ
  since there are tightly integrated with base code (the user base is however
  much smaller than TikZ)
* its key-value syntax is quite predictible, once you're used at it.
* you can have XML and EPUB output (default is PDF)
* smaller base than LaTeX if you install it as a standalone (260M,
  mostly because of fonts). I could'nt manage to install the Mkiv standalone version
  (being too stupid to patch its install script), but Hans Hagen
  released a distribution of luametatex, the development version of ConTeXt, a
  few weeks ago and it is available for OpenBSD.
  http://www.pragma-ade.com/install.htm

  Troubles with pdf inclusions can be bypassed uploading
  those luametatex binaries after installation
  http://dl.contextgarden.net/build/luametatex/amd64-openbsd6.6/luametatex

Regards,

Damien Thiriet

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Roderick
In reply to this post by Oliver Leaver-Smith

On Wed, 6 Nov 2019, Oliver Leaver-Smith wrote:

> The use case I have is for a novel which should require less formatting
> than a technical book, so I should be able to retrofit that after once
> I have investigated the many tools mentioned in the thread.

Plain TeX would mean in that case a simple text file with few formatting
tags, for example for italics and boldface. Then you can generate
a postcript file with tex and dvips commands and print it, if you want.
Later you can perfectionate it.

To read the first pages of "The TeXBook" would be enough for the beginning,
and you find a pdf version googling for it.

nroff is interesting, because is a unix standard from the beginning
and (in the meantime only almost) everywhhere, but is more complicated
to learn, the source less readable, and the result not better.

Rodrigo

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Martin Schröder
In reply to this post by Oliver Leaver-Smith-2
Am Sa., 2. Nov. 2019 um 16:06 Uhr schrieb Oliver Leaver-Smith
<[hidden email]>:
> What tools do people find useful for writing on OpenBSD? By writing I mean long form such as novels and technical books, including plot and character development, outlining, and formatting for publishing (not all the same application necessarily)

Some writers swear on Scrivener. It's proprietary and Mac/Win only, though.

Best
    Martin

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Adam Thompson
In reply to this post by Peter Nicolai Mathias Hansteen
On 2019-11-02 11:14, Peter Nicolai Mathias Hansteen wrote:

>> 2. nov. 2019 kl. 16:00 skrev Oliver Leaver-Smith <[hidden email]>:
>>
>> What tools do people find useful for writing on OpenBSD? By writing I
>> mean long form such as novels and technical books, including plot and
>> character development, outlining, and formatting for publishing (not
>> all the same application necessarily)
>>
>> I have found a number which boast Linux support, but not really
>> anything that stands out which supports OpenBSD (aside from the
>> obvious LaTeX et al.)
>
> I really can’t speak to plot and character development, but all three
> editions of The Book of PF were written using OpenOffice and later
> LibreOffice write on OpenBSD snapshots.
>
> Earlier versions of that manuscript were developed using DocBook SGML
> (editing with emacs), but the publisher (fortunately) did not want any
> truck with that.
>
> For any new projects I would likely look half-heartedly for something
> markdown based but would probably end up going the LibreOffice route
> again.


FWIW, Brian Kernighan's new book was written using groff(1), with final
rasterization done by gs(1), obviously there's a number of other tools
involved.

On the other hand, unless you name is Brian Kernighan (or possibly
Kristaps, Ingo, or jmc@) I doubt that toolset will satisfy you :-).

A few people around here have used TeX, LaTeX, and LyX (a LaTeX
front-end) all of which are very much capable of large projects split
into sections/chapters/etc.
  AFAIK OpenBSD's LaTeX / TeX packages are all more than adequate to the
task, and all of the necessary tools are in ports.

-Adam

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Joe Davis
In reply to this post by Oliver Leaver-Smith-2
> Some writers swear on Scrivener. It's proprietary and Mac/Win only, though.

Manuskript[1] looks promising as a foss alternative. Haven't attempted
to build it on OpenBSD. None of the dependencies look to be a major
problem.

Cheers,
Joe

[1]: http://www.theologeek.ch/manuskript/

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Mark Jamsek
Joe Davis wrote

>> Some writers swear on Scrivener. It's proprietary and Mac/Win only,
>> though.
>
> Manuskript[1] looks promising as a foss alternative. Haven't attempted
> to build it on OpenBSD. None of the dependencies look to be a major
> problem.
>
> Cheers,
> Joe
>
> [1]: http://www.theologeek.ch/manuskript/

This looks really interesting. Thanks for sharing, Joe.



--
Sent from: http://openbsd-archive.7691.n7.nabble.com/openbsd-user-misc-f3.html

Reply | Threaded
Open this post in threaded view
|

Re: Tools for writers

Steve Litt
In reply to this post by Oliver Leaver-Smith
On Wed, 6 Nov 2019 15:36:42 +0000
Oliver Leaver-Smith <[hidden email]> wrote:

> Thanks everyone for recommendations, I think I am just going to use
> VimOutliner for development and outlining. The use case I have is for
> a novel which should require less formatting than a technical book,
> so I should be able to retrofit that after once I have investigated
> the many tools mentioned in the thread.

If you can't find a VimOutliner to LaTeX converter, let me know,
because I have a very rudimentary one that "does the right thing" for
all heading hierarchy elements, and for body text. Obviously, you'll
need to create a separate file that maps indent level to
Part/Chapter/Section/Subsection ... because not all LaTeX files use the
same hierarchy. Note also that this is a one-way trip: The instance you
start modifying the text you're pretty much stuck in LaTeX. My
converter requires you to create an empty doc with the correct
headings, etc, the correct document preamble, and the final \bye.

Doing the same thing for XHTML is trivial.

SteveT

Steve Litt
November 2019 featured book: Manager's Guide to Technical
Troubleshooting Second edition
http://www.troubleshooters.com/mgr

1234