On 19 April 2018 at 19:41, Jan Iversen <j...@apache.org> wrote: > > > Sent from my iPad > >> On 19 Apr 2018, at 17:10, sebb <seb...@gmail.com> wrote: >> >>> On 19 April 2018 at 13:27, sebb <seb...@gmail.com> wrote: >>> I have done some further investigation of using JSON and Jekyll. >>> >>> I think JSON is not the best format for maintenance. >>> This is because it is messy including chunks of text (e.g. for >>> additional info on the project). >>> Also it does not allow any comments. >>> The format is rather strict, with lots of quotes needed, and brackets >>> and braces. >>> >>> I think we should use YAML for the raw data, and (if necessary) >>> extract a subset into a JSON file for external consumption. > Personally I think it is a mistake. json is rather simple, and are supported > everywhere. Yaml on the other hand is less supported (e.g. looked for an > online validator without success). Safari and xcode formats json nicely > whereas yaml is viewed as raw text.
The problem is that JSON gets very messy for anything but a short text string. This is not particularly obvious with the current contents, because the longest text string is the description. But even now, some of the lines are very long. > Why do we need comments in the file, it has not been needed until now, so let > us not introduce “hidden” data. Allowing comments is just an additional benefit; it's not the reason for choosing YAML. Sometimes it's useful to be able to add a TODO to a part of a data file. Or explain why a particular value is present. But again; not the reason for changing. > but of course it is a matter of taste (just like js was). > > extracting a json file from the yaml file seems to be overdoing it. Again, only if necessary. >>> >>> As to Jekyll: >>> >>> Jekyll can equally use a YAML data file, so it is not a problem >>> changing to YAML. >>> >>> At present the attic-test PoC includes a single JSON data file which >>> is processed in a plugin script that generates the individual page >>> data. >>> >>> This works well (and it looks like BuildBot supports the use of Jekyll >>> plugin scripts - other sites such as GitHub may not) >>> >>> But I think it would be better to have a separate YAML file per project. >>> >>> Jekyll can process these as part of a collection. >>> This avoids the need to use a plugin to generate the pages. >>> I think it also makes it a bit more obvious what is going on (each >>> output file has an input file) >>> >>> And the YAML body can contain arbitrary markup to be added to the >>> generated page. >>> This would make it easier to preserve the extra information present in >>> some of the existing xml files >>> >>> A question: >>> On a tablet, would it be harder to maintain one file per project >>> rather than a single large file? > significantly ! that was one of the major reasons for my js solution. > I don't understand. Why is a single file easier? Surely each new retirement just needs to have a new file? Does it matter that there is no other data in it? I tried adding more data from the XML files to see if I could reproduce all the information on the current pages. It's really difficult to ensure that all the quoting is done correctly; a single misplaced quote affects the entire file. Eclipse started having problems, but even in a plain text editor it was awkward to handle. > but let us focus on the solution wanted by the community and what a single > person needs. > > rgds > jan i >>> >>> i.e. instead of updating projects.json one would need to create/update >>> a projects/project.md file. >> >> I have updated the attic-test tree with a YAML-based version: >> >> https://svn.apache.org/repos/asf/attic/site-test/yaml >> >> The yaml.sh script in the parent directory will create the output in docs3/. >> This should currently be identical to the output in docs2/ - apart >> from the date in feed.xml >> >> If this looks like it will be suitable for use when working from >> tablets, I can tidy it up and start migrating some of the additional >> text from the xdocs/projects files >> >> If not, please advise what needs to be done to make it possible to >> update the site from a tablet.
