taskReproducible paper template - Tasks: task #15823, Generating About webpages from...


You are not allowed to post comments on this tracker with your current authentication level.

task #15823: Generating About webpages from README-hacking.md

Submitted by:  Boud Roukema <boud>
Submitted on:  Thu 26 Nov 2020 04:32:19 AM UTC  
Should Start On:  Thu 26 Nov 2020 12:00:00 AM UTC Should be Finished on:  Thu 26 Nov 2020 12:00:00 AM UTC
Category:  Webpage Priority:  5 - Normal
Status:  Done Privacy:  Public
Percent Complete:  100% Assigned to:  Pedram Ashofteh Ardakani <pedram>
Open/Closed:  Closed Effort:  0.00

Sat 28 Nov 2020 11:52:22 PM UTC, comment #5: 

Thanks a lot Pedram, I just added a "Category" for documentation as you suggested, and defined task #15825 to completing a Texinfo documentation.

I also added a figure from the original paper, visualizing the Maneage file structure in the Project architecture page. For the time being with the manual corrections, the webpage is nicely consistent with Maneage and the paper and we'll even make it better as we progress more.

So I will close this task and we'll discuss the full Texinfo documentation in task #15825.

Mohammad Akhlaghi <makhlaghi>
Project Administrator
Sat 28 Nov 2020 09:10:42 PM UTC, comment #4: 

comment #3:

Sure! "Less is more" of course :) Converting and trying to patch things up or break them down can be demanding and confusing. As Boud points out, consistency is important. And what tool better than `Texinfo' when it comes down to writing neat and `Maneagable' documentations ;)

You already got me hooked with introducing the Gnuastro documentation (and getting familiar with `Texinfo' in general).

Building on your suggestion, maybe we should also start up a new `Documentation' category and move things there?

Pedram Ashofteh Ardakani <pedram>
Project MemberIn charge of this item.
Fri 27 Nov 2020 09:52:34 PM UTC, comment #3: 

Thanks a lot Pedram for the nice review of the markdown converters, its a great resource to have.

I was thinking about the same thing: a simple script can be written to break up the 'README-hacking.md' into each sections, then feed them into the converter to create separate HTML pages.

But generally, Markdown is a not a good documentation format and has always annoyed me. I started 'README-hacking.md' in Markdown because of historical reasons (it was initially part of 'README.md', then it grew large and I just copied it to another file, and it grew! But I have been planning on adding a proper documentation for Maneage in Texinfo for a long time, there were just more important things to focus on.

With Texinfo we'll be able to automatically generate webpages, an elegant PDF, and info pages that Maneage users can directly access on the command-line within their own projects (for example with '.local/bin/info maneage').

The raw source of the Texinfo can be in the core Maneage branch, and its PDF and info formats can built during './project configure'. For us developers, we can build its HTMLs and put them in the webpage.

What do you think? If you agree, we can change the title of this task into starting a Texinfo manual and not spend time and energy on the different markdown converters.

Mohammad Akhlaghi <makhlaghi>
Project Administrator
Fri 27 Nov 2020 07:37:29 PM UTC, comment #2: 

Thanks, Boud and Mohammad.

In the previous version, I used a Perl script developed by John Gruber and then fixed some issues and added extra formatting manually.

I have been trying out various Markdown to HTML convertors such as:

"lowdown" looks like a proper candidate for the following reasons:

  • Open source and under the ISC license
  • Works offline
  • Written in C (no need to install extra software)
  • Provides the option to print out the result in pure HTML without the unnecessary tags such as `<head>`, `<body>` and `<script>`
  • Keeps the indentations in the source `.md` file

It looks like this solves the second problem mentioned in comment #1.

Now about the problem with the "about" page. Mohammad, the way you used the `Texinfo` style in the about pages and broke it up is pretty neat! :thumbs_up:
But here's the thing: Are we going to have the same content in the `README-hacking.md` file and the about pages? If so, we can come up with some script that reads the Markdown file and splits it into particular HTML files named after their section title.

It would be great if you could elaborate :)

Pedram Ashofteh Ardakani <pedram>
Project MemberIn charge of this item.
Thu 26 Nov 2020 05:25:51 AM UTC, comment #1: 

Thanks Boud, the README-hacking.md file has been on the webpage from the start: in the About page. But there were two problems:

  • It was very long (which was the main complaint from the referee, so they had suggested to break it up).
  • The indentation of the Make recipes had been removed! So the Make commands were not correct! This was actually first observed in the Tutorial page by Raul.

For now, I fixed both of these issues manually.

However, another problem still remains: its not up to date. Pedram had previously written a Perl script to convert README-hacking.md to the single about.html page.

So the Perl script just needs to be corrected for the two points above and we need to put it somewhere (maybe in the webpage git repository). In this way, we can always keep the "About" pages and README-hacking.md up to date.

So I am assigning this task to Pedram and slightly modified the title to account for these.

Mohammad Akhlaghi <makhlaghi>
Project Administrator
Thu 26 Nov 2020 04:32:19 AM UTC, original submission:  

Two suggestions from the review of the main research paper about the criteria which Maneage is intended to satisfy are the following:

  • improve the consistency between the paper [1] [2] and the website [3] [4]
  • include the README-hacking.md information on the website

[1] submitted version 1: https://doi.org/10.5281/zenodo.3872247

[2] submitted version 1: https://arxiv.org/abs/2006.03018

[3] https://maneage.org

[4] https://gitlab.com/pedramardakani/maneage-webpage

Both are good suggestions that should not be delayed too long.

Boud Roukema <boud>
Project Member


No files currently attached


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -email is unavailable- added by pedram (Posted a comment)
  • -email is unavailable- added by makhlaghi (Posted a comment)
  • -email is unavailable- added by boud (Submitted the item)

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.




    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-11-28 makhlaghi StatusIn Progress => Done
        Percent Complete20% => 100%
        Open/ClosedOpen => Closed
    2020-11-27 pedram CategoryNone => Webpage
        StatusNone => In Progress
        Percent Complete0% => 20%
    2020-11-26 makhlaghi Assigned toNone => pedram
        SummaryWebpage: Maneage paper consistency; README-hacking.md => Generating About webpages from README-hacking.md

    Back to the top

    Powered by Savane 3.5