search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 808 forks source link

"Migrating from AsciiDoc Python" Content Discussion #434

Closed jaredmorgs closed 8 years ago

jaredmorgs commented 8 years ago

http://asciidoctor.org/docs/user-manual/#compared-to-asciidoc is currently available to create content for.

Use this issue as a tracker for content suggestions, or feel free to provide PRs referencing this ticket to keep track of contributions.

elextr commented 8 years ago

I think you are doing asciidoctor a disservice with this section, it is not competing with asciidoc, it does not need to be compared with it, there is a detailed annex for those who need to know the specifics for porting documents.

Just acknowledge Asciidoc Python as the initial implementation that compatibility mode matches and thats all that is necessary.

mojavelinux commented 8 years ago

I agree with @elextr. AsciiDoc is the language, Asciidoctor is the processor (just as AsciiDoc Python is a processor).

This section made it's way into the document from an early outline, but I don't think there's a need for it. The correct place for any content discussing the differences between Asciidoctor and AsciiDoc is the compatibility section (Appendix A, http://asciidoctor.org/docs/user-manual/#asciidoctor-vs-asciidoc). That section could perhaps have a small migration guide for people switching from the AsciiDoc Python processor to the Asciidoctor processor.

jaredmorgs commented 8 years ago

Feel free to do a PR to delete this section, @elextr

Unless I beat you to it. 😉

On Sun, 17 Jan 2016, 12:03 Dan Allen notifications@github.com wrote:

I agree with @elextr https://github.com/elextr. AsciiDoc is the language, Asciidoctor is the processor (just as AsciiDoc Python is a processor).

This section made it's way into the document from an early outline, but I don't think there's a need for it. The correct place for any content discussing the differences between Asciidoctor and AsciiDoc is the compatibility section (Appendix A, http://asciidoctor.org/docs/user-manual/#asciidoctor-vs-asciidoc). That section could perhaps have a small migration guide for people switching from the AsciiDoc Python processor to the Asciidoctor processor.

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/asciidoctor.org/issues/434#issuecomment-172284412 .

Sent from Mobile.

rockyallen commented 8 years ago

Can I disagree please? If you want the user manual to be the ultimate source of Asciidoctor information, I think you need to address compatibility in it. And if you just delete this section, it leaves Appendix A orphaned. However I agree with @mojavelinux in http://discuss.asciidoctor.org/Improve-documentation-for-converting-from-Asciidoc-Python-td4216.html that the manual should be focussed on Asciidoctor. The better solution is to use this section to describe Asciidoc Python briefly, and refer out to the existing compatibility guide http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/. Then move Appendix A from the user manual to the compatibility guide, and expand it there into a proper migration guide.

rockyallen commented 8 years ago

Oops - I should have checked out master before speaking. I see there is now a migrating from asciidoc section, but I still think it would all be better moved into the guide.

rockyallen commented 8 years ago

Is there an agreed way forward for this wrt upgrading from Asciidoc python please? There is currently:

and I have some notes from the attribute trawl that should find a home.

I don't think it needs to be a very large section, but should it be centralized, and where?

mojavelinux commented 8 years ago

Of course you can disagree :)

I do think we should have a section that is focused on how to migrate a document written with AsciiDoc Python in mind to Asciidoctor. I don't think we need to cover how AsciiDoc Python works or any of its quirks. We should just focus on the content and what needs to change. It's also a good opportunity to introduce the shorthands and conveniences that Asciidoctor brings (the Asciidoctor writing style).

The section should cover the following topics:

The focus should be on the stuff that really matters. There are thousands of minute differences that most people would never notice (like whether something is indented more or less in the output).

The section should also introduce compat-mode and explain how to use it to minimize the number of changes required.

mojavelinux commented 8 years ago

I've updated the title of the issue to reflect the new focus of the content. We aren't comparing to AsciiDoc Python, we are migrating from it. We are AsciiDoc.

rockyallen commented 8 years ago

So: Update appendix A with

  1. Compat-mode
  2. Changed command line options
  3. Summarize syntax that must be changed when not using compat-mode. Ref current migration guide for details.
  4. integration changes (source highlighters, how math is rendered, etc)
  5. added restrictions and other recommendations
  6. attributes that are deprecated/not implemented (extracted from the current table) with Asciidoctor alternatives
  7. Any changes to "standard" Asciidoc extensions - music, latex, source, graphviz
  8. Highlight new extensions (ditaa etc)
  9. Pointer to the new way of writing extensions
  10. new shorthand and other syntax conveniences. Link to 'good practise' guide.

Delete the current table.

Delete all references to the compatibility file, this is about migrating TO Asciidoctor.

Ignore all the X- stuff in the compatibility guide; 0.14 is dead.

Rename to "Migrating from Asciidoc Python to Asciidoctor" !?

mojavelinux commented 8 years ago

attributes that are deprecated/not implemented (extracted from the current table) with Asciidoctor alternatives

I agree that this is a great place to document attributes we have omitted elsewhere. It puts them in context while making it clear that they are deprecated / historical.

mojavelinux commented 8 years ago

Any changes to "standard" Asciidoc extensions - music, latex, source, graphviz

I'd rather leave this information out for the most part. I've always felt like the documentation for those extensions was very poor and their usage is extremely low. We could mention LaTeX, but only to mention that asciidoctor-latex is available but takes a slightly different approach and appeals to a different audience. Of course, graphviz has evolved into a much more comprehensive Asciidoctor Diagram.

mojavelinux commented 8 years ago

Ignore all the X- stuff in the compatibility guide; 0.14 is dead.

There are still some uses for this as it lets you use compat-mode at the element level. I can't say how pervasive it is (probably not), but we still might want to think about whether it has an important role to play.

mojavelinux commented 8 years ago

Migrating from Asciidoc Python to Asciidoctor

I think the "Asciidoctor" part is understood, so just "Migrating from AsciiDoc Python"

rockyallen commented 8 years ago

PR updated

mojavelinux commented 8 years ago

A few more things to include:

The asciidoctor command does not support the --help manpage option (yet). If you install Asciidoctor using a Linux package, you can type:

$ man asciidoctor

If you install Asciidoctor using RubyGems, you can type:

$ man "`gem which asciidoctor | xargs dirname`/../man/asciidoctor.1"

Asciidoctor styles the first paragraph of the preamble as a "lead paragraph". A lead paragraph has a larger font size than normal paragraph content. This effect is activated by the default stylesheet. If you don't like it, you can tweak the stylesheet or add additional CSS to reverse the effect.

rockyallen commented 8 years ago

PR updated

mojavelinux commented 8 years ago

Merged as 34e9687 with additional revisions in 77b6b8c.

I moved this section into the "Conversations and Migrations" part instead of an appendix as it felt more fitting there.

We should deals with any improvements to this section in subsequent issues. The focus of this issue was to get this section seeded, which has bee accomplished.