Re: Some Assistance Please

[Adonay Felipe Nogueira]

I can't say what's wrong with DocBook, because using Org is a personal
preference of mine, so first and most important: This is personal
opinion.

* Pros of Org Mode

- Org Mode's markup is easier to understand and start using. No need to
  remember tag names (at least for most used formating functions). One
  thing that bothers me in most markup languages is the need to either
  rememeber English words, or some abbreviation of them for which a
  non-native would find difficult to.

- Exports to LaTeX, LaTeX Beamer, Org (again), PDF, ODT, ePUB
  (perhaps), plain text, HTML, MarkDown (with features unsupported by
  MarkDown being exported to HTML), and TeXInfo. There are more export
  options that I might be unaware of.

- Supports ordered, unordered and description lists. Ordered lists can
  make use of Arabic (1, 2, ...) or Roman (I, II, ...) numbers.

  - Ordereded lists using letters can be enabled with a variable,
although they are discouraged due to their letter limit.

- Supports defining the counter with which an ordered list will start
  with, with this you can force the continuation of an ordered list if
  for some reason the counter was broken, or do lists starting with
  0. :)

- Depending on the object/thing being referenced and the exported file,
  links can reference to specific parts of other files. Furthermore,
  links/references to places in the same Org file (or exported file) can
  be created for anything, not just sections.

- Supports tables (via either the default table feature or Tabl.el
  Emacs package) and formulas (which can also make use of Emacs Calc
  formulas). Can also be extended with tools such as Gnuplot so that you
  can make charts based on the table data (this support can be enabled
  by toggling the respective Org Babel options), or tools such as GNU R
  so that you can make more advanced statistic calculations (the same
  note in the previous parenthesis applies, now for GNU R), and from
  within GNU R you can make use of the ggplot2 library to make the plots
  or charts directly from R (no need to enable Gnuplot in Org Babel).

- Parts of the Org document using Org Babel and some scripting language
  can take tables (except *maybe* for those formated in Tabl.el),
  first-level lists, strings and numbers as input.

- Each section can be exported to individual files, no need to make one
  file for each section. This way you can keep a large Org file with all
  documentation possible inside.

- Supports including other Org files, or other text/document files
  depending on the export format.

- Supports including images.

- Depending on the export format, supports including SVG, PDF and PGF
  (or TikZ) drawings with .tex file extension.

* Cons of Org Mode

- The community still has to figure a way so that, while using a
  table in Emacs Tabl.el syntax, which can have merged cells (contrary
  to Org Mode tables), there would be also the possibility of using
  formulas. Currently, you either have to decide to use formulas in a
  table, or to make merged cells, you can't mix both.

  - Personal note: I tend to stay with Org Mode tables because I don't
need merged cells, and if would find myself tempted to use it, I
would find a way to describe the content in a shorter way --- that
is, if keeping formulas is a must, otherwise I make use of merged
cells.

- The community has to improve BibTeX interaction while exporting to any
  format. Currently, my personal setup, which works fine for my needs,
  makes use of a script that I wrote whuch uses Org BiBTeX and BibTeX.el
  packages to extract at least reference key (use for in-document
  links), author, title, year, copyright license and URI of the work.
  But since I'm not a developer, and I have limited knowledge on Emacs
  Lisp, I'm unable to do fancy things like sorting, inserting suffixes
  in the years (when the reference would be similar to an existing one),
  extract more BibTeX fields than those mentioned, and so on.

- Providing tables formated with Tabl.el to Org Babel code blocks might
  not work as expect. Although I didn't test this yet.

- Currently, providing lists to Org Babel code blocks takes into account
  only the first level of the list.

-- 
- [[https://libreplanet.org/wiki/User:Adfeno]]
- Palestrante e consultor sobre /software/ livre (não confundir com
  gratis).
- "WhatsApp"? Ele não é livre, por isso não uso. Iguais a ele prefiro
  GNU Ring, ou Tox. Quer outras formas de contato? Adicione o vCard
  que está no endereço acima aos teus contatos.
- Pretende me enviar arquivos .doc, .ppt, .cdr, ou .mp3? OK, eu
  aceito, mas não repasso. Entrego apenas em formatos favoráveis ao
  /software/ livre. Favor entrar em contato em caso de dúvida.
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Some Assistance Please

[Adrien Monteleone]

Thank you Derek,

This improves my understanding of the current situation considerably.

Certainly as I noted, I have no issue using the present methods.

Thank you for taking the time to explain this.

Regards,

Adrien

> On May 25, 2017, at 9:45 AM, Derek Atkins  wrote:
> 
> Adrien,
> 
> Adrien Monteleone  writes:
> 
>> Geert,
>> 
>> If the opposite were possible, would that meet the needs?
>> 
>> If using the wiki as the collaboration platform opened up
>> documentation editing to non-developer types but still gave you the
>> desired formats, is that what you are looking for or are there other
>> needs?
> 
> This was the road we've looked at and attempted in the past -- moving
> the documentation development onto the Wiki and then using that to
> produce the various formats required for yelp, windows help, etc.  The
> results were less than stunning.
> 
> This is why we're reluctant to try again without an existence proof that
> the tools have significantly improved and will produce documentation
> that is at least as good as the current process.
> 
>> Looking over mediawiki.org, there are methods using our own render
>> server (or a public one if so desired) and extension plugins to export
>> a variety of formats including XHTML, PDF, ePUB, ZIM, ODF, and yes,
>> DocBook XML. There’s also the option of using PediaPress for people to
>> order a physical bound copy if they so desire.
> 
> If we could translate into Docbook then we could leverage the existing
> tools to generate the outputs we require.  However, how well does the
> tool translate from wiki -> Docbook?
> 
>> The only one presently offered I don’t see included as an extension is
>> MOBI though there are many tools to take any of those other formats to
>> MOBI if really needed. I would think it not too difficult to script
>> the conversion of a resulting ePUB into MOBI. Clicking the MOBI
>> download link could take a trip through ePUB and then the ePub2Mobi
>> conversion to serve the desired file. Is there still a significant
>> case for .mobi files due to .mobi only readers? Is there a current
>> comparison of download stats from gnucash.org?
> 
> I dont know if there are download stats available from code and/or www.
> 
>> An additional advantage of using the wiki as the working and
>> publishing platform is that formats are generated on-demand by the
>> render server. Thus any time someone downloads a copy of the
>> documentation it will always be the most up to date, rather than a
>> milestone-released static version. If that is not desired I suppose
>> some method of drafts vs. published approved pages would suffice, but
>> that will more than likely be handled by control of editing
>> credentials.
> 
> That's not desired; we want the documentation to match the release.
> Someone with 2.4 is better served with the 2.4 documentation.  Someone
> with 2.6 with the 2.6 documentation.  Someone running 2.4 who looks at
> the 2.6 docs might get confused.
> 
>> The render server can also be configured to ‘publish’ specific
>> collections of articles so that the wiki could contain the entirety of
>> the help, tutorial and concepts guide, developer documentation, et
>> cetera, and then particular links will give you a single file of any
>> one of those. So if someone wanted a printed copy of the help and a
>> pdf of the tutorial and concepts guide, they could get each separately
>> all from the wiki and all with the most current approved edits.
> 
> The developer documentation is generated by doxygen from the source
> code.  Moving that into the wiki would be, IMHO, the wrong thing to do.
> The dev docs should live with the code.
> 
>> Just a thought.
>> 
>> -Adrien
> 
> -derek
> -- 
>   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
>   Member, MIT Student Information Processing Board  (SIPB)
>   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
>   warl...@mit.eduPGP key available

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Some Assistance Please

[Derek Atkins]

Adrien,

Adrien Monteleone  writes:

> Geert,
>
> If the opposite were possible, would that meet the needs?
>
> If using the wiki as the collaboration platform opened up
> documentation editing to non-developer types but still gave you the
> desired formats, is that what you are looking for or are there other
> needs?

This was the road we've looked at and attempted in the past -- moving
the documentation development onto the Wiki and then using that to
produce the various formats required for yelp, windows help, etc.  The
results were less than stunning.

This is why we're reluctant to try again without an existence proof that
the tools have significantly improved and will produce documentation
that is at least as good as the current process.

> Looking over mediawiki.org, there are methods using our own render
> server (or a public one if so desired) and extension plugins to export
> a variety of formats including XHTML, PDF, ePUB, ZIM, ODF, and yes,
> DocBook XML. There’s also the option of using PediaPress for people to
> order a physical bound copy if they so desire.

If we could translate into Docbook then we could leverage the existing
tools to generate the outputs we require.  However, how well does the
tool translate from wiki -> Docbook?

> The only one presently offered I don’t see included as an extension is
> MOBI though there are many tools to take any of those other formats to
> MOBI if really needed. I would think it not too difficult to script
> the conversion of a resulting ePUB into MOBI. Clicking the MOBI
> download link could take a trip through ePUB and then the ePub2Mobi
> conversion to serve the desired file. Is there still a significant
> case for .mobi files due to .mobi only readers? Is there a current
> comparison of download stats from gnucash.org?

I dont know if there are download stats available from code and/or www.

> An additional advantage of using the wiki as the working and
> publishing platform is that formats are generated on-demand by the
> render server. Thus any time someone downloads a copy of the
> documentation it will always be the most up to date, rather than a
> milestone-released static version. If that is not desired I suppose
> some method of drafts vs. published approved pages would suffice, but
> that will more than likely be handled by control of editing
> credentials.

That's not desired; we want the documentation to match the release.
Someone with 2.4 is better served with the 2.4 documentation.  Someone
with 2.6 with the 2.6 documentation.  Someone running 2.4 who looks at
the 2.6 docs might get confused.

> The render server can also be configured to ‘publish’ specific
> collections of articles so that the wiki could contain the entirety of
> the help, tutorial and concepts guide, developer documentation, et
> cetera, and then particular links will give you a single file of any
> one of those. So if someone wanted a printed copy of the help and a
> pdf of the tutorial and concepts guide, they could get each separately
> all from the wiki and all with the most current approved edits.

The developer documentation is generated by doxygen from the source
code.  Moving that into the wiki would be, IMHO, the wrong thing to do.
The dev docs should live with the code.

> Just a thought.
>
> -Adrien

-derek
-- 
   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
   Member, MIT Student Information Processing Board  (SIPB)
   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
   warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel