On Wed, 2017-01-25 at 09:21 +0000, Ola Fosheim Grøstad via Digitalmars- d wrote:
> On Tuesday, 24 January 2017 at 14:27:15 UTC, aberba wrote:
> > Which one works well? I'm more concerned about syntax highlighting and line numbering (in some cases). Support for custom fonts.
> 
> If you don't mind XML then you might consider http://docbook.org/

Asciidoc (and it's continuation Asciidoctor) was invented to be a human usable front end to the DocBook/XML toolchain – and it still works for this. Humans should not have to write XML. Hence Asciidoctor.

-- 
Russel. ============================================================================= Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder@ekiga.net 41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel@winder.org.uk London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

On Tue, 2017-01-24 at 16:38 +0000, bachmeier via Digitalmars-d wrote:
> On Tuesday, 24 January 2017 at 15:02:26 UTC, Russel Winder wrote:
> 
> > I wouldn't use Markdown for such a project.
> 
> Is there a reason?

Unless life has changed, the support for indexing, tables of contents,
floating images, tables, etc. is missing from Markdown.

> > Many people might choose Asciidoctor.
> 
> When I looked at asciidoc, it looked like markdown with extensions.

Or put another way Markdown is a stripped down Asciidoctor (or ReStructuredText) for creating single HTML pages with no complicated content.

Word (or if you are lucky LibreOffice) is the way most publishers want authors to write. XeLaTeX and Asciidoctor (as a front end to a DocBook/XML toolchain) are the route for end-user construction of press PDF.

-- 
Russel. ============================================================================= Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder@ekiga.net 41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel@winder.org.uk London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

On Tue, 2017-01-24 at 19:34 +0000, qznc via Digitalmars-d wrote:
> On Tuesday, 24 January 2017 at 14:27:15 UTC, aberba wrote:
> > Which one works well? I'm more concerned about syntax highlighting and line numbering (in some cases). Support for custom fonts.
> 
> I used Sphinx here: https://qznc.github.io/d-tut/
> 
> The syntax "ReStructured Text" is more ugly than Markdown, but has more features (e.g. different kinds of blocks). Sphinx can generate HTML, LaTeX, EPub, and more.
> 
> http://www.sphinx-doc.org/

ReStructuredText and Sphinx is used in many places, but much of it is
ugly, particularly compared to Asciidoctor (which has it's own warts)
and XeLaTeX (which also has some).

In the end it all gets tribal, and is down to personal taste.

I am sad for the demise of FrameMaker on Solaris.

-- 
Russel. ============================================================================= Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder@ekiga.net 41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel@winder.org.uk London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

On Wednesday, 25 January 2017 at 10:57:41 UTC, Russel Winder wrote:
> Asciidoc (and it's continuation Asciidoctor) was invented to be a human usable front end to the DocBook/XML toolchain – and it still works for this. Humans should not have to write XML. Hence Asciidoctor.

I might look into Asciidoc at some point then. There are decent grammar-directed XML editors out there, and plain XML is ok too in my opinion. As you mentioned OpenOffice also has some support for docbook filters.

Another option is to do your own XML based off HTML5 if HTML is a primary target.

On Tuesday, 24 January 2017 at 14:27:15 UTC, aberba wrote:
> Which one works well? I'm more concerned about syntax highlighting and line numbering (in some cases). Support for custom fonts.

Depends on what you want to achieve. LaTeX has loads of packages that can be installed and you can create professional looking layouts. It is quite impressive. I know people who write articles and their Ph.D. thesis in LaTeX to get maximum control over the layout (to avoid Word-like surprises). LaTeX is accepted by many publishers, printers etc., especially in the tech sector. The downside is the source code. It's not very nice to read and you get lost easily. And try to get back after a year and change something! Also, you have to convert it to PDF each time you wanna (proof)read it, so you usually deal with two layouts at the same time (source code and PDF/HTML), which is time consuming and error prone.

From what I can see, Markdown is much nicer to read and you don't need to switch between source code and layout all the time, but it is rather limited in comparison to LaTeX. You wouldn't have the fine grained control over the layout and you would most likely have to convert it to something else before you can send it to a publisher / printer. They don't want to waste time with exotic or lesser known formats, because they have their own infrastructure set up, which leads me to the next point.

A lot of publishers will prefer Word, because they can easily edit it and if they have their own layout section, they will transform Word to txt and paste it into say Adobe InDesign.

So if you want to publish privately on your homepage or blog, pick whatever you want. If you want to publish on one of those self-publishing websites, check what they support. If you want the old fashioned publisher ask them first what format they want. Believe me, you can safe a lot of time. Imagine you create the perfect layout with LaTeX and then the publisher goes "Thanks, er, can you please send it to me as a Word doc?"

I for my part have stopped worrying about it too much. Just write the text (in Word or an Ascii editor) and think about the layout later. It helps you to focus on the content rather than on the optical structure - and if you have to change, add, delete or re-arrange things, it won't cause you any headaches. Write first, design later.

On Wednesday, 25 January 2017 at 11:01:14 UTC, Russel Winder wrote:

> Or put another way Markdown is a stripped down Asciidoctor (or ReStructuredText) for creating single HTML pages with no complicated content.

There are packages out there that can get generate some decent looking output, like Gitbook and Mkdocs. Scrivener also has Markdown support and can compile it to all of its normal output targets (epub, mobi, pdf, html, etc..).

On Wednesday, 25 January 2017 at 11:01:14 UTC, Russel Winder wrote:
> On Tue, 2017-01-24 at 16:38 +0000, bachmeier via Digitalmars-d wrote:
>> On Tuesday, 24 January 2017 at 15:02:26 UTC, Russel Winder wrote:
>> 
>> > I wouldn't use Markdown for such a project.
>> 
>> Is there a reason?
>
> Unless life has changed, the support for indexing, tables of contents,
> floating images, tables, etc. is missing from Markdown.

I see. You were referring to the original Markdown specification, which does not have those features. There are many extensions, though, like https://bookdown.org/

On Wednesday, 25 January 2017 at 14:37:31 UTC, bachmeier wrote:
>
> I see. You were referring to the original Markdown specification, which does not have those features. There are many extensions, though, like https://bookdown.org/

Nice. How does "bookdown" or any other extension fare regarding fine grained layout control à la LaTeX?

On Wednesday, 25 January 2017 at 14:51:58 UTC, Chris wrote:
> On Wednesday, 25 January 2017 at 14:37:31 UTC, bachmeier wrote:
>>
>> I see. You were referring to the original Markdown specification, which does not have those features. There are many extensions, though, like https://bookdown.org/
>
> Nice. How does "bookdown" or any other extension fare regarding fine grained layout control à la LaTeX?

It is a layer on top of Pandoc with useful extensions for creating books. Pandoc allows you to add arbitrary LaTeX code to the document, so AFAIK, you should be able to do anything you can do with LaTeX. Most of that would be handled with modifications to the .latex template or with a yaml section at the top of the document.

On Wednesday, 25 January 2017 at 16:29:18 UTC, bachmeier wrote:
> On Wednesday, 25 January 2017 at 14:51:58 UTC, Chris wrote:
>> Nice. How does "bookdown" or any other extension fare regarding fine grained layout control à la LaTeX?
>
> It is a layer on top of Pandoc with useful extensions for creating books. Pandoc allows you to add arbitrary LaTeX code to the document, so AFAIK, you should be able to do anything you can do with LaTeX. Most of that would be handled with modifications to the .latex template or with a yaml section at the top of the document.

The best of both worlds, in other words.