On 19 April 2018 at 21:08, Jan Iversen <j...@apache.org> wrote: > > > Sent from my iPad > >> On 19 Apr 2018, at 22:02, sebb <seb...@gmail.com> wrote: >> >>> 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. > I do not understand what “messy” means, json allows multiple lines text (see > in my attic.js) using a ` instead of a “, that way yaml and json are equal > “messy”.
The attic.js file is not JSON format; it is Javascript source. JS is much more flexible. > I have another project where json is used to store translations (loaded with > php), and that is sometimes 3/4 of a page, easy readable due to the multiline > feature. Again, I assume the JSON is embedded using PHP syntax. > but please see this as just a factual correction, if you prefer yaml I am the > last to go against it. > Have a look at some of the .md files and see. I think they are much simpler. > rgds > jan i >> >>> 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.
